Events

Conversations API: Webhook Event Types

The Conversations API enables you to monitor conversation changes in real-time using webhooks. Three key event types are supported:

Event Types

1. conversation.created

   • Use Case: Monitor the initiation of new customer interactions.

   • Triggered: When a new conversation is created.

2. conversation.updated

   • Use Case: Track changes in active conversations, such as updated statuses or participant modifications.

   • Triggered: When an existing conversation is updated, with changes in attributes, participants, or statuses.

3. conversation.deleted

   • Use Case: Maintain clean data or trigger processes when conversations are archived or removed.

   • Triggered: When a conversation is deleted.

These events allow you to track the lifecycle of conversations efficiently.

Webhook Payload Example

conversation.updated Event Payload

{
  "service": "conversations",
  "event": "conversation.updated",
  "payload": {
    "id": "badbf15c-bad3-4bf3-9223-6b7f414f9770",
    "name": "",
    "description": "",
    "status": "active",
    "visibility": "private",
    "accessibility": "invite-only",
    "featuredParticipants": [
      {
        "id": "7dadb14e-91bb-4eb7-8b9e-7827dd74bf70",
        "type": "contact",
        "status": "active",
        "displayName": "Jane Doe",
        "avatarUrl": "",
        "contact": {
          "identifierKey": "facebookid-509207435603226",
          "identifierValue": "27612960145016998",
          "platformAddress": "27612960145016998"
        }
      },
      {
        "id": "5795352d-f111-407b-be33-c9db94e4a666",
        "type": "user",
        "status": "active",
        "displayName": "John Smith",
        "avatarUrl": ""
      }
    ],
    "activeParticipantCount": 2,
    "pendingParticipantCount": 0,
    "initiatingParticipant": {
      "id": "7dadb14e-91bb-4eb7-8b9e-7827dd74bf70",
      "type": "contact",
      "status": "active",
      "displayName": "Jane Doe",
      "avatarUrl": "",
      "contact": {
        "identifierKey": "facebookid-509207435603226",
        "identifierValue": "27612960145016998",
        "platformAddress": "27612960145016998"
      }
    },
    "channelId": "8963269e-69e4-58aa-9bf0-9b6cc239329c",
    "lastMessage": {
      "id": "1ffdfcf0-5e4f-426b-adbc-c698b4bfc949",
      "type": "text",
      "preview": {
        "text": "hallo"
      },
      "recipients": null,
      "status": "delivered",
      "sender": {
        "id": "7dadb14e-91bb-4eb7-8b9e-7827dd74bf70",
        "type": "contact",
        "status": "active",
        "displayName": "Jane Doe",
        "avatarUrl": "",
        "contact": {
          "identifierKey": "facebookid-509207435603226",
          "identifierValue": "27612960145016998",
          "platformAddress": "27612960145016998"
        }
      },
      "createdAt": "2024-11-27T19:33:53.504Z"
    },
    "createdAt": "2024-11-26T18:45:28.809Z",
    "updatedAt": "2024-11-27T19:33:53.515Z",
    "platformStyle": "direct"
  }
}

Webhook Configuration

Webhook Configuration for Conversation Events

To subscribe to conversation events, you need to configure a webhook with the following parameters:

Property	Description	Example Value
Event Filters	Optional filters to narrow the scope of events, such as by channelId.	channelId:12345
Signing Key	Key used for verifying the authenticity of incoming webhook requests.	abc123xyz456
URL	The endpoint to which event notifications will be sent.	https://example.com/webhook
Event	The specific event to track, options include conversation.created, conversation.updated, conversation.deleted.	conversation.created
Service	The service to monitor.

Webhook Configuration Example

{
  "service": "conversations",
  "event": "conversation.created",
  "url": "http://site",
  "signingKey": "key",
  "eventFilters": [
    {
      "key": "channelId",
      "value": "<id>"
    }
  ]
}