Callbacks

⚡ Callback Events

🏢 Conversation endpoints:

This section details the structure of callback events related to the resource: conversations Please note that all events include a tid (transactionId) to correlate request and response. Developers are expected to safely store the synchronously returned tid param as part of response headers (synchronous)

✅ Success events

The success events include conversation:created and conversation:updated events

conversation:created

Sent in response to: Create conversation - POST /conversations

JSON

{
  "event": "conversation:created",
  "tid": "8ebbe593-1730-4b63-96ee-380eacc85d35",
  "tenantId": "fe738a59-dd6a-4151-9720-495b7dc4f4a9",
  "status": "success",
  "code": <code>,
  "description": "<description>",
  "value": {
    "conversationId": "CSR1923712361272",
    "aliasId": "d1fa5281-eab3-4f74-afd2-9bab70b03c07",
    "messages": [{
      "messageId": "<uuid>",
      "aliasId": "<unique-external-reference-id>"
    }],
    "routedTo": {
      "teamId": "d1fa5281-eab3-4f74-afd2-9bab70b03c07",
      "skillId": "d1fa5281-eab3-4f74-afd2-9bab70b03c07"
    }
  },
  "headers": {},
  "context": {}
}

conversation:updated

Sent in response to: Update conversation - PATCH /conversations/<conversationId>

JSON

{
  "event": "conversation:updated",
  "tid": "8ebbe593-1730-4b63-96ee-380eacc85d35",
  "tenantId": "fe738a59-dd6a-4151-9720-495b7dc4f4a9",
  "status": "success",
  "code": <code>,
  "description": "<description>",
  "value": {},
  "headers": {},
  "context": {}
}

conversation:transfer

Sent in response to: Transfer conversation - POST /conversations/<conversationId>/transfer

JSON

{
  "event": "conversation:transfer",
  "tid": "8ebbe593-1730-4b63-96ee-380eacc85d35",
  "tenantId": "fe738a59-dd6a-4151-9720-495b7dc4f4a9",
  "status": "success", //or failed
  "code": <code>,
  "description": "<description>",
  "value": {},
  "headers": {},
  "context": {}
}

❌ Error events

conversation:error

Sent in response to:

• Create conversation - POST /conversations
• Update conversation - PATCH /conversations/<conversationId>
• Transfer conversation - POST /conversations/<conversationId>/transfer

JSON

{
  "event": "conversation:error",
  "tid": "8ebbe593-1730-4b63-96ee-380eacc85d35",
  "tenantId": "fe738a59-dd6a-4151-9720-495b7dc4f4a9",
  "status": "failed",
  "code": <code>,
  "description": "<description>",
  "value": {},
  "headers": {},
  "context": {}
}

🏢 Conversation - Message endpoints:

This section details the structure of callback events related to the sub-resource: messages Please note that all events include a tid (transactionId) to correlate request and response. Developers are expected to safely store the synchronously returned tid param as part of response headers (synchronous)

✅ Success events

The success events include conversation-message:appended and conversation-message:receipt events

conversation-message:appended

Sent in response to: Append message - POST /conversations/<conversationId>/messages

JSON

{
  "event": "conversation-message:appended",
  "tid": "8ebbe593-1730-4b63-96ee-380eacc85d35",
  "tenantId": "fe738a59-dd6a-4151-9720-495b7dc4f4a9",
  "status": "success",
  "code": <code>,
  "description": "<description>",
  "value": {
    "messages": [{
      "messageId": "<uuid>",
      "aliasId": "<unique-external-reference-id>"
    }]
  },
  "headers": {},
  "context": {}
}

conversation-message:receipt

Sent in response to: Append message - POST /conversations/<conversationId>/messages. This event covers the following lifecycle states: delivered, readand failed

Delivered

{
    "event": "conversation-message:receipt",
    "tid": "0100a600-ee2e-4fdc-86d5-cebbbe34e51b",
    "status": "success",
    "code": 4679,
    "description": "Message delivered successfully",
    "errorDetails": null,
    "tenantId": "00f4fbf5-082d-48d0-94f6-d35c3fae0894",
    "value": {
        "conversationId": "CQAZQJCFA0LF84R4",
        "aliasId": "",
        "messages": [
            {
                "aliasId": null,
                "messageId": "238d6365-c470-47fb-9848-803db3b97728"
            }
        ]
    },
    "context": {
        "key1": "value1"
    }
}

Read

{
    "event": "conversation-message:receipt",
    "tid": "0100a600-ee2e-4fdc-86d5-cebbbe34e51b",
    "status": "success",
    "code": 4678,
    "description": "Message read",
    "errorDetails": null,
    "tenantId": "00f4fbf5-082d-48d0-94f6-d35c3fae0894",
    "value": {
        "conversationId": "CQAZQJCFA0LF84R4",
        "aliasId": "",
        "messages": [
            {
                "aliasId": null,
                "messageId": "238d6365-c470-47fb-9848-803db3b97728"
            }
        ]
    },
    "context": {
        "key1": "value1"
    }
}

Failed

{
    "event": "conversation-message:receipt",
    "tid": "46945a76-a338-4fe3-896d-831e679af9af",
    "status": "failure",
    "code": 4680,
    "description": "Message delivery failed",
    "errorDetails": [
        "Message delivery failed"
    ],
    "tenantId": "00f4fbf5-082d-48d0-94f6-d35c3fae0894",
    "value": {
        "conversationId": "CQAZQJCFA0LF84R4",
        "aliasId": "",
        "messages": [
            {
                "aliasId": null,
                "messageId": "7c470de0-d44f-48aa-9fc9-f94520bbac5a"
            }
        ]
    },
    "context": {
        "key1": "value1"
    }
}

❌ Error events

Sent in response to: Append message - POST /conversations/<conversationId>/messages

conversation-message:error

JSON

{
  "event": "conversation-message:error",
  "tid": "8ebbe593-1730-4b63-96ee-380eacc85d35",
  "tenantId": "fe738a59-dd6a-4151-9720-495b7dc4f4a9",
  "status": "failed",
  "code": <code>,
  "description": "<description>",
  "value": {},
  "headers": {},
  "context": {}
}

Delete Messages

✅ Success events

conversation-messages:deleted

Sent in response to: Delete message - DELETE /conversations/<conversationId>/messages

JSON

{
    "event": "conversation-messages:deleted",
    "tid": "8ebbe593-1730-4b63-96ee-380eacc85d35",
    "tenantId": "fe738a59-dd6a-4151-9720-495b7dc4f4a9",
    "status": "success",
    "code": 1234,
    "description": "Message(s) deleted successfully",
    "value": {}
}

❌ Error events

Partial success: conversation-messages:error

Sent in response to: Delete message - DELETE /conversations/<conversationId>/messages

JSON

{
  "event": "conversation-messages:error",
  "tid": "8ebbe593-1730-4b63-96ee-380eacc85d35",
  "tenantId": "fe738a59-dd6a-4151-9720-495b7dc4f4a9",
  "status": "partial_with_errors",
  "code": <code>,
  "description": "Some message(s) could not be deleted",
  "value": {
    "failedRecords": [
      {
          "messageId": "<messageId provided in the request>",
          "aliasId": "<messageId provided in the request>",
          "reason": "Invalid messageId"
      },
      {
          "messageId": "<messageId provided in the request>",
          "aliasId": "<messageId provided in the request>",
          "reason": "Invalid aliasId"
      },
      {
          "messageId": "<messageId provided in the request>",
          "aliasId": "<messageId provided in the request>",
          "reason": "Internal server error"
      }
    ]
  }
}

Failure: conversation-messages:error

JSON

{
  "event": "conversation-messages:error",
  "tid": "8ebbe593-1730-4b63-96ee-380eacc85d35",
  "tenantId": "fe738a59-dd6a-4151-9720-495b7dc4f4a9",
  "status": "failed",
  "code": <code>,
  "description": "Message(s) could not be deleted",
  "value": {}
}

🏢 Conversation - Participants endpoints:

This section details the structure of callback events related to the sub-resource: participants Please note that all events include a tid (transactionId) to correlate request and response. Developers are expected to safely store the synchronously returned tid param as part of response headers (synchronous)

✅ Success events

The success events include conversation:created and conversation:updated events

conversation-participant:added

Sent in response to: Add participant - POST /conversations/<conversationId>/participants

JSON

{
  "event": "conversation-participant:added",
  "tid": "8ebbe593-1730-4b63-96ee-380eacc85d35",
  "tenantId": "fe738a59-dd6a-4151-9720-495b7dc4f4a9",
  "status": "success",
  "code": <code>,
  "description": "<description>",
  "value": {},
  "headers": {},
  "context": {}
}

conversation-participant:removed

Sent in response to: Delete participant - DELETE /conversations/<conversationId>/participants

JSON

{
  "event": "conversation-participant:removed",
  "tid": "8ebbe593-1730-4b63-96ee-380eacc85d35",
  "tenantId": "fe738a59-dd6a-4151-9720-495b7dc4f4a9",
  "status": "success",
  "code": <code>,
  "description": "<description>",
  "value": {},
  "headers": {},
  "context": {}
}

❌ Error events

conversation-participant:error

Sent in response to:

• Add participant - POST /conversations/<conversationId>/participants
• Delete participant - DELETE /conversations/<conversationId>/participants

JSON

{
  "event": "conversation-participant:error",
  "tid": "8ebbe593-1730-4b63-96ee-380eacc85d35",
  "tenantId": "fe738a59-dd6a-4151-9720-495b7dc4f4a9",
  "status": "failed",
  "code": <code>,
  "description": "<description>",
  "value": {},
  "headers": {},
  "context": {}
}