Working with webhook

For testing webhook functionality, you can use this service

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

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).

Your webhook will receive requests from different IP addresses. Use the “Webhook Secret” setting for verification and authorization.

Requests to your webhook will come from IP addresses located in the territory of the Russian Federation.

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

{
  "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)	Event type. Currently, only events for new messages and test requests are implemented, but others may be added in the future. Depending on this parameter, the set of fields may change. test_request - an event we will send to your webhook when you press the test button in Suvvy's control panel. We recommend checking this parameter and ignoring the request if event_type != "new_messages".
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	Direct download link for the file. For example: https://i.imgur.com/ucYKBpa.png The file will be located on our server.
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