Webhooks
This method pertains to setting up and configuring webhooks to receive various conversation events. These events include new messages from users and updates on the status of outbound messages.
When a webhook trigger occurs, a POST request containing a JSON payload will be sent to the configured webhook URL.
Make sure that your application responds to webhooks with a 200 response to ensure proper functionality
This table lists all possible options for the type of an event message.
| Type | Description |
|---|---|
MESSAGE_CREATED | New message received by our platform |
MESSAGE_DELIVERY | Delivery status updates of one message |
USER_EVENT | User related events like subscription |
TEMPLATE_STATUS_UPDATE | Template status updates |
TEMPLATE_CATEGORY_UPDATE | Template category updates |
Message Delivery status
The Conversations API platform generates event notifications with the type MESSAGE_DELIVERY to provide status updates on previously sent messages.
Message Delivery status codes are detailed below ('status' parameter).
| Code | Description |
|---|---|
| DELIVERED | the message was delivered to the user |
| READ. | the message was read by the user |
| SENT | the message was sent to the provider |
| REJECTED | the message was rejected by our platform |
| FAILED | the message failed to be sent |
| EXPIRED | the message was not delivered in time |
| UNKNOWN | the message status is unknown |
In case of unsuccessful message deliveries, the platform will provide specific error codes ('errorCode' parameter) to indicate the cause of the failure.
| Code | Description |
|---|---|
| 1 | Unknown |
| 2 | User Not Subscribed |
| 3 | Price or Cost config Not Found |
| 4 | An error with your media. Could be an unsupported file format, etc |
| 5 | Free Test Quota Exceeded For Messages |
| 6 | Channel server unreachable |
| 7 | Monthly minimum fee not found |
| 8 | Template error |
| 9 | Quick Reply invalid item count, should be between 2 and 5 |
| 10 | Channel integration configuration not found |
| 11 | Overloaded |
| 12 | Your balance is not sufficient for this transaction |
| 13 | Route configuration not found |
| 14 | The business is not eligible or the template ID is not allowed for the business |
| 15 | Not found registered device for the phone number or message undeliverable due user preferences / legal reason |
| 16 | carrier network retry exceed |
| 17 | API Request rejected |
| 100 | User Not Found |
| 300 | Country not allowed |
| 301 | SMS request not success |
| 302 | App Route configuration not found |
| 303 | Channel is not activated |
User events
Our platform will push an event with type USER_EVENT each time an end-user changed their subscription preference.
This table lists all possible options for the type of an event message.
| Type | Description |
|---|---|
SUBSCRIBED | The user has subscribed |
UNSUBSCRIBED | The user has unsubscribed |
TAG_ASSIGN | User tag assignment has been updated |
Errors
In the event of an unsuccessful webhook request, the system will attempt up to 3 additional retries within a 15-minute timeframe.
The interval between each retry will increase exponentially if the target does not respond with a success code (2XX) or an unresolvable error.
Furthermore, if no response is received within 20 seconds, the system will consider it a failure and initiate a retry.
📄️ Create a webhook
Create or update a webhook
📄️ List webhooks
List webhooks