API Reference

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

{ "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>

{ "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

{ "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
{ "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

{ "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

{ "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" } }
{ "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" } }
{ "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
{ "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

{ "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

{ "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
{ "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

{ "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

{ "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
{ "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": {} }