# Receiving Callback

{% hint style="info" %}
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:password@example.com/callback>"
* explicit transmission of ip-address and port. Example: "callbackUrl": "[http://12.34.567.89:8080/callback](https://api.direct.revicom.ltd/messages/http:/12.34.567.89:8080/callback)"
  {% endhint %}

## Outbound Messages Callback <a href="#outbound_callback" id="outbound_callback"></a>

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 | <p>Getting one of the message statuses:</p><ul><li>delivered – the message was delivered</li><li>undelivered – the message was not delivered in lifetime (default 25 hours)</li><li>unsent – the message was not sent</li></ul><p>Is the default event, if there is a callbackUrl and no callbackEvents in the query.</p> |
| sent      | Getting the message status “sent”                                                                                                                                                                                                                                                                                         |
| read      | <p>Getting one of the message statuses:</p><ul><li>read – the message was read</li><li>unread – the message was not read in lifetime (default 25 hours)</li></ul>                                                                                                                                                         |
| price     | Changing the message price                                                                                                                                                                                                                                                                                                |
| click     | Clicking on a shortened link in the text of the message                                                                                                                                                                                                                                                                   |

### Message status change <a href="#status_callback" id="status_callback"></a>

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          | <p>string</p><p><em>required</em></p>  | Message uuid                                                                                |
| channel\_type          | <p>string</p><p><em>required</em></p>  | [Message channel](/extra/references.md#channel-types)                                       |
| cascade\_message\_uuid | <p>string</p><p><em>optional</em></p>  | Identifier of the first message in the cascade. This is sent for cascading messages only    |
| cascade\_step          | <p>integer</p><p><em>optional</em></p> | The sequence number of the message in the cascade. This is sent for cascading messages only |
| callback\_event        | <p>string</p><p><em>required</em></p>  | [Callback event](/extra/references.md#callback-events)                                      |
| status                 | <p>string</p><p><em>required</em></p>  | [Message status](/extra/references.md#message-states)                                       |
| status\_time           | <p>string</p><p><em>required</em></p>  | Message status time                                                                         |
| error\_code            | <p>integer</p><p><em>optional</em></p> | [Error code](/extra/references/error-codes.md)                                              |

### Message price change <a href="#price_callback" id="price_callback"></a>

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          | <p>string</p><p><em>required</em></p>  | Message uuid                                                                                                          |
| channel\_type          | <p>string</p><p><em>required</em></p>  | [Message channel](/extra/references.md#channel-types)                                                                 |
| cascade\_message\_uuid | <p>string</p><p><em>optional</em></p>  | Identifier of the first message in the cascade. This is sent for cascading messages only                              |
| cascade\_step          | <p>integer</p><p><em>optional</em></p> | The sequence number of the message in the cascade. This is sent for cascading messages only                           |
| callback\_event        | <p>string</p><p><em>required</em></p>  | Callback event. In this case: `price`                                                                                 |
| parts                  | <p>integer</p><p><em>required</em></p> | Number of parts in the message                                                                                        |
| price                  | <p>number</p><p><em>required</em></p>  | Price of the message                                                                                                  |
| currency               | <p>string</p><p><em>required</em></p>  | Price currency. Three-digit letter code according to [ISO 4217](https://www.iso.org/ru/iso-4217-currency-codes.html)​ |
| price\_time            | <p>string<br><em>required</em></p>     | Message price setting time                                                                                            |

### Click through <a href="#click_callback" id="click_callback"></a>

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          | <p>string</p><p><em>required</em></p>  | Message uuid                                                                                |
| channel\_type          | <p>string</p><p><em>required</em></p>  | [Message channel](/extra/references.md#channel-types)                                       |
| cascade\_message\_uuid | <p>string</p><p><em>optional</em></p>  | Identifier of the first message in the cascade. This is sent for cascading messages only    |
| cascade\_step          | <p>integer</p><p><em>optional</em></p> | The sequence number of the message in the cascade. This is sent for cascading messages only |
| callback\_event        | <p>string</p><p><em>required</em></p>  | Callback event. In this case: `click`                                                       |
| url                    | <p>string</p><p><em>required</em></p>  | Initial link                                                                                |
| short\_url             | <p>string</p><p><em>required</em></p>  | Shortened link​                                                                             |
| click\_time            | <p>string<br><em>required</em></p>     | Click time                                                                                  |

## Inbound Messages Callback <a href="#inbound_callback" id="inbound_callback"></a>

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 <a href="#inbound_sent_callback" id="inbound_sent_callback"></a>

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   | <p>string<br><em>required</em></p> | Message uuid                                                                                               |
| callback\_event | <p>string<br><em>required</em></p> | Callback event. In this case: `inbound_sent`                                                               |
| channel\_type   | <p>string<br><em>required</em></p> | [Message channel](/extra/references.md#channel-types)                                                      |
| status          | <p>string<br><em>required</em></p> | Message status. In this case: `inbound_sent`                                                               |
| status\_time    | <p>string<br><em>requied</em></p>  | Time of sending                                                                                            |
| item            | <p>object<br><em>required</em></p> | Message object in the form of the response object [GET /v1/message​](/messages/sms-sending.md#sending-sms) |

## Expected response <a href="#response" id="response"></a>

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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://api.direct.revicom.ltd/messages/callback.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.