# Working with webhook

{% hint style="info" %}
For testing webhook functionality, you can use [this service](https://webhook.site/)
{% endhint %}

To connect a custom channel, you need to specify the webhook to which Suvvy will send messages. It will send them in the following format:

## Request

{% hint style="danger" %}
Your webhook must return a status code between **200 and 299** and respond within **20 seconds**. Otherwise, the request will be considered failed, and the messages will be marked as undelivered *(such messages are not visible to Suvvy)*.
{% endhint %}

{% hint style="warning" %}
Your webhook will receive requests from **different IP addresses**. Use the **“Webhook Secret”** setting for verification and authorization.
{% endhint %}

{% hint style="warning" %}
Requests to your webhook will come from IP addresses located in the territory of the **Russian Federation.**
{% endhint %}

We will make a **POST** request to your webhook, passing a body in the following format:

```json
{
  "event_type": "new_messages",
  "new_messages": [
    {
      "type": "image",
      "message_sender": "ai",
      "file": {
        "name": "image.png",
        "url": "<direct link to the image>",
        "size_bytes": 10240,
        "mime_type": "image/png"
      }
    },
    {
      "type": "text",
      "message_sender": "ai",
      "text": "Hello! How can I help you?"
    }
  ]
}
```

If you specified a **webhook secret** during the custom channel connection, we will pass it in the `Authorization` header in the following format:

```
Bearer <your secret>
```

### Object in Request

| Field          | Type                                      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| -------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `event_type`   | string (`new_messages` or `test_request`) | <p><strong>Event type.</strong> Currently, only events for new messages and test requests are implemented, but others may be added in the future.</p><p></p><p>Depending on this parameter, the set of fields may change.</p><p><code>test\_request</code> - an event we will send to your webhook when you press the test button in Suvvy's control panel.</p><p></p><p>We recommend checking this parameter and ignoring the request if <code>event\_type != "new\_messages"</code>.</p> |
| `new_messages` | array of `Message` objects                | **New messages.** Present only if the event type is `new_messages`.                                                                                                                                                                                                                                                                                                                                                                                                                        |

#### `Message` Object

| Field            | Type                                          | Description                                                                                                                |
| ---------------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `type`           | string (`text`, `image`, `audio`, `document`) | **Message type.** The set of fields depends on this parameter.                                                             |
| `message_sender` | string (`ai` or `employee`)                   | **Message sender.** Present in all types, determines who sent the message (bot or employee through Suvvy's control panel). |
| `text`           | string                                        | **Message text.** Present only if the message type is `text`.                                                              |
| `file`           | `MessageFile` object                          | **Attached file.** Present only if the message type is `image`, `audio`, or `document`.                                    |

#### `MessageFile` Object

| Field        | Type                                    | Description                                                                                                                                                                                                               |
| ------------ | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `url`        | string                                  | <p><strong>Direct download link for the file.</strong></p><p></p><p>For example: <a href="https://i.imgur.com/ucYKBpa.png"><https://i.imgur.com/ucYKBpa.png></a></p><p></p><p>The file will be located on our server.</p> |
| `name`       | string                                  | **File name.**                                                                                                                                                                                                            |
| `size_bytes` | integer ∈ `[0, +∞)`                     | **File size in bytes.**                                                                                                                                                                                                   |
| `mime_type`  | string `^[a-zA-Z0-9]+/[a-zA-Z0-9-.+]+$` | **Mime-type of the file.**                                                                                                                                                                                                |

Suvvy can send files of the following types:

* For images: `image/png`, `image/jpeg`, `image/gif`
* For audio: `audio/ogg`, `audio/mpeg`, `audio/wav`, `audio/x-wav`, `audio/webm`, `audio/mp4`, `audio/m4a`, `audio/x-m4a`
* For documents: **any**, including the above-mentioned types