Receiving Callback

The callbackUrl value must comply with RFC 3986, which specifically allows:

• use of both https and http secure zone

• transmission of a login:password pair for Basic authorization. Example:"callbackUrl": "https://login:[e-mail]/callback"

• explicit transmission of ip-address and port. Example: "callbackUrl": "http://12.34.567.89:8080/callback"

Outbound Messages Callback

If the callbackUrl parameter (and optionally callbackEvents) was transmitted in the message object when requesting to send POST /v1/message, then when one of the specified events (or the default event) occurs, a callback will be sent to the specified callbackUrl.

Event	Description
delivered	Getting one of the message statuses: delivered – the message was delivered undelivered – the message was not delivered in lifetime (default 25 hours) unsent – the message was not sent Is the default event, if there is a callbackUrl and no callbackEvents in the query.
sent	Getting the message status “sent”
read	Getting one of the message statuses: read – the message was read unread – the message was not read in lifetime (default 25 hours)
price	Changing the message price
click	Clicking on a shortened link in the text of the message

Message status change

When any of the delivered, sent, read events specified in the message sending request occurs, the following query will be sent to the specified callbackUrl:

POST {{callback_url}}
Content-Type: application/json
[
  {
    "message_uuid": "063464ec-a34f-4558-90c5-984395000003",
    "channel_type": "SMS",
    "cascade_message_uuid": "063464ec-a34f-4558-90c5-984395000002",
    "cascade_step": 2,
    "callback_event": "delivered",
    "status": "undelivered",
    "status_time": "2020-10-16T18:51:13Z",
    "error_code": 6969
  }
]

Parameter	Type	Description
message_uuid	string required	Message uuid
channel_type	string required	Message channel
cascade_message_uuid	string optional	Identifier of the first message in the cascade. This is sent for cascading messages only
cascade_step	integer optional	The sequence number of the message in the cascade. This is sent for cascading messages only
callback_event	string required	Callback event
status	string required	Message status
status_time	string required	Message status time
error_code	integer optional	Error code

Message price change

When the price event occurs, if it was specified in the message sending request, the following query will be sent to the specified callbackUrl:

POST {{callback_url}}
Content-Type: application/json
[
  {
    "message_uuid": "063464ec-a34f-4558-90c5-984395000003",
    "channel_type": "SMS",
    "cascade_message_uuid": "063464ec-a34f-4558-90c5-984395000002",
    "cascade_step": 2,
    "callback_event": "price",
    "parts": 5,
    "price": 0.1,
    "currency": "EUR",
    "price_time": "2020-10-16T18:51:13Z"
  }
]

Parameter	Type	Description
message_uuid	string required	Message uuid
channel_type	string required	Message channel
cascade_message_uuid	string optional	Identifier of the first message in the cascade. This is sent for cascading messages only
cascade_step	integer optional	The sequence number of the message in the cascade. This is sent for cascading messages only
callback_event	string required	Callback event. In this case: price
parts	integer required	Number of parts in the message
price	number required	Price of the message
currency	string required	Price currency. Three-digit letter code according to ISO 4217​
price_time	string required	Message price setting time

Click through

When the click event occurs, if it was specified in the request to send a message, the following query will be sent to the specified callbackUrl:

POST {{callback_url}}
Content-Type: application/json
[
  {
    "message_uuid": "063464ec-a34f-4558-90c5-984395000003",
    "callback_event": "click",
    "channel_type": "SMS",
    "cascade_message_uuid": "31d6f174-2ef6-4f25-b03b-c4c06e0e4df8",
    "cascade_step": 3,
    "url": "https://revicom.ltd",
    "short_url": "a.bc/61EwQ",
    "click_time": "2021-04-21T17:41:43Z"
  }
]

Parameter	Type	Description
message_uuid	string required	Message uuid
channel_type	string required	Message channel
cascade_message_uuid	string optional	Identifier of the first message in the cascade. This is sent for cascading messages only
cascade_step	integer optional	The sequence number of the message in the cascade. This is sent for cascading messages only
callback_event	string required	Callback event. In this case: click
url	string required	Initial link
short_url	string required	Shortened link​
click_time	string required	Click time

Inbound Messages Callback

1. Contact your manager to enable the option to get inbounds (currently only possible for the WhatsApp channel)

2. Go to the PA page Settings / Inbounds

3. Click Add and fill out the form

4. In the field Traffic Partitioning Center, specify the traffic partitioning center to which incoming messages should be assigned

5. In the field Callback URL, specify the address to which the callback will be sent when an inbound is got

If Include sender names is specified, you can select the names for inbounds of which the selected TPC and CallbackUrl will be assigned (if you do not take into account names, then the assignment of TPC and CallbackUrl will be valid for all inbounds via the channel)

Inbounds for which no matching rule is found will be assigned to the default TPC (specified on the Settings/Traffic Partitioning Centers page).

Receiving inbound message

When an inbound is got for which a suitable rule with CallbackUrl was found, the following query will be sent to the specified address:

POST {{callback_url}}
[
  {
    "message_uuid": "063464ec-9999-4558-90c5-984395000001",
    "callback_event": "inbound_sent",
    "channel_type": "WHATSAPP",
    "status": "inbound_sent",
    "status_time": "2021-11-15T18:38:07Z",
    "item": {
      "createdTime": "2021-12-06T16:31:22.892Z",
      "sentTime": "2021-11-15T18:38:07.000Z",
      "messageUuid": "063464ec-9999-4558-90c5-984395000001",
      "direction": "inbound",
      "channelType": "WHATSAPP",
      "trafficCenterId": 111,
      "senderName": "UNDELIV2",
      "destination": "14085553911",
      "content": "message text",
      "specialContent": {
        "text": "message text",
        "contentType": "text"
      },
      "totalParts": 1
    }
  }
]

Parameter	Type	Description
message_uuid	string required	Message uuid
callback_event	string required	Callback event. In this case: inbound_sent
channel_type	string required	Message channel
status	string required	Message status. In this case: inbound_sent
status_time	string requied	Time of sending
item	object required	Message object in the form of the response object GET /v1/message​

Expected response

In response to a callback of any type, HTTP code 2** is expected. If there is no response within 24 hours, resending will be performed every 5 minutes.