Sending messages

To send messages from a custom channel, use the following method:

Method	POST
URL	https://api.suvvy.ai/api/webhook/custom/message

Headers

Header	Value
Authorization	Bearer <token>
Content-Type	application/json

A token obtained when connecting the channel must be included in the request.

Request Body

{
  "api_version": 1,
  "message_id": "<message id>",
  "chat_id": "<chat id>",
  "text": "Hello!",
  "attachments": [
    {
      "file_name": "file.png",
      "file_type": "image",
      "data": "aHR0cHM6Ly93d3cueW91dHViZS5jb20vd2F0Y2g/dj1kUXc0dzlXZ1hjUQ=="
    }
  ],
  "source": "Ivanov Ivan from Avito",
  "placeholders": {
     "some_id": "123123"
  },
  "link": {
    "type": "chat",
    "hint": "Dialogue",
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  },
  "message_sender": "customer",
  "client_name": "Ivanov Ivan",
  "client_phone": "[phone]"
}

Field	Field Required	Type	Description
api_version	yes	integer (only 1)	API Version. In the future, we will update our API, and to avoid any disruptions, we will support old versions in parallel for a while.
message_id	yes	string	Message ID in your system. Necessary to prevent accidental re-triggers.
chat_id	yes	string	Chat ID in your system. The linking part that determines which dialogue the message will appear in.
text	yes, if attachments field is not specified	string, at least 1 character	Message text.
attachments	yes, if text field is not specified	array of Attachment objects	Attachments. Currently, only images and audio are supported.
message_sender	yes	string (customer or employee)	Message sender. Customer or employee from your system.
source	yes	string	Source. The value that appears in the "Source" column in the Suvvy dashboard. Typically, the client's name or username, or the deal name.
link	no	Link object	Link to chat in your system. Will be displayed as a button in the Suvvy dashboard.
placeholders	no	object, where key and value are strings	Variables for instructions. More details below.
client_name	no	string	Client name.
client_phone	no	string	Client phone number.

Variables

Attachment Object

All fields are required.

Field	Type	Description
file_name	string	File name.
file_type	string (image or audio)	File type.
data	string, base64 of file	File. Permissible types are indicated below.

Suvvy accepts 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

Maximum file size - 15 megabytes

Link Object

Field	Type	Description
type	string (user, chat, phone, lead, other)	Link type. Affects the icon displayed in the dashboard user - 👤 chat - 💬 phone - 📞 lead - 🤝🏻 other - 🔗
hint	string or null	Text for button. Optional. If not specified (or null), titles are used depending on the type: user - Account chat - Chat phone - Phone lead - Lead other - Link
url	string	Link.

Response

Upon success, the webhook returns a body of the following form:

{
  "message": "Successful"
}

This can be ignored as it doesn't carry useful information.

Errors

Invalid Token

Returns a body of the following type and code 401:

{
  "detail": "Invalid token.",
  "status_code": 401,
  "error_code": "auth_invalid_token"
}

Channel Disabled

Returns when the channel is not connected or disabled in settings. Returns a body of the following type and code 424:

{
  "detail": "Channel is disabled.",
  "status_code": 424,
  "error_code": "instance_channel_is_disabled"
}

Unsupported File Type

Returns when the submitted file is unsupported by Suvvy. Provides supported types. Returns a body of the following type and code 415:

{
  "detail": "File type is not supported or invalid.",
  "status_code": 415,
  "error_code": "file_invalid_type",
  "allowed_mime_types": [
    "image/png",
    "text/csv",
    "audio/ogg"
  ]
}

Negative Balance

Returns when your Suvvy balance is below zero. Returns a body of the following type and code 402:

{
  "detail": "Your balance is below zero, so you can't perform this action.'",
  "status_code": 402,
  "error_code": "user_balance_below_zero"
}

Validation Error

Returns code 422 and a body detailing what was submitted incorrectly.

Code Examples

Python (requests)

import requests

response = requests.post(
    'https://api.suvvy.ai/api/webhook/custom/message',
    headers={
        'Authorization': 'Bearer your_token',
        'Content-Type': 'application/json'
    },
    json={
        'api_version': 1,
        'message_id': 'unique_message_id',
        'chat_id': 'unique_chat_id',
        'text': 'Hello!',
        'attachments': [
            {
                'file_name': 'file.png',
                'file_type': 'image',
                'data': 'base64_file_data'
            }
        ],
        'source': 'John Doe from Avito',
        'placeholders': {
            'some_id': '123123'
        },
        'link': {
            'type': 'chat',
            'hint': 'Dialogue',
            'url': 'https://www.youtube.com/watch?v=dQw4w9WgXcQ'
        },
        'message_sender': 'customer',
        'client_name': 'John Doe',
        'client_phone': '[phone]'
    }
)

JavaScript (fetch)

fetch('https://api.suvvy.ai/api/webhook/custom/message', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer your_token',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        api_version: 1,
        message_id: 'unique_message_id',
        chat_id: 'unique_chat_id',
        text: 'Hello!',
        attachments: [
            {
                file_name: 'file.png',
                file_type: 'image',
                data: 'base64_file_data'
            }
        ],
        source: 'John Doe from Avito',
        placeholders: {
            some_id: '123123'
        },
        link: {
            type: 'chat',
            hint: 'Dialogue',
            url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ'
        },
        message_sender: 'customer',
        client_name: 'John Doe',
        client_phone: '[phone]'
    })
});

PHP (cURL)

$ch = curl_init('https://api.suvvy.ai/api/webhook/custom/message');
$data = [
    'api_version' => 1,
    'message_id' => 'unique_message_id',
    'chat_id' => 'unique_chat_id',
    'text' => 'Hello!',
    'attachments' => [
        [
            'file_name' => 'file.png',
            'file_type' => 'image',
            'data' => 'base64_file_data'
        ]
    ],
    'source' => 'John Doe from Avito',
    'placeholders' => [
        'some_id' => '123123'
    ],
    'link' => [
        'type' => 'chat',
        'hint' => 'Dialogue',
        'url' => 'https://www.youtube.com/watch?v=dQw4w9WgXcQ'
    ],
    'message_sender' => 'customer',
    'client_name' => 'John Doe',
    'client_phone' => '[phone]'
];
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer your_token',
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

Ruby (net/http)

require 'net/http'
require 'uri'
require 'json'

uri = URI.parse('https://api.suvvy.ai/api/webhook/custom/message')
header = {
  'Authorization' => 'Bearer your_token',
  'Content-Type' => 'application/json'
}
data = {
  api_version: 1,
  message_id: 'unique_message_id',
  chat_id: 'unique_chat_id',
  text: 'Hello!',
  attachments: [
    {
      file_name: 'file.png',
      file_type: 'image',
      data: 'base64_file_data'
    }
  ],
  source: 'John Doe from Avito',
  placeholders: {
    some_id: '123123'
  },
  link: {
    type: 'chat',
    hint: 'Dialogue',
    url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ'
  },
  message_sender: 'customer',
  client_name: 'John Doe',
  client_phone: '[phone]'
}

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(uri.request_uri, header)
request.body = data.to_json

response = http.request(request)

Rust (reqwest)

use reqwest::blocking::Client;
use serde_json::json;
use std::error::Error;

fn main() -> Result<(), Box<dyn Error>> {
    let client = Client::new();
    let res = client.post("https://api.suvvy.ai/api/webhook/custom/message")
        .header("Authorization", "Bearer your_token")
        .header("Content-Type", "application/json")
        .json(&json!({
            "api_version": 1,
            "message_id": "unique_message_id",
            "chat_id": "unique_chat_id",
            "text": "Hello!",
            "attachments": [
                {
                    "file_name": "file.png",
                    "file_type": "image",
                    "data": "base64_file_data"
                }
            ],
            "source": "John Doe from Avito",
            "placeholders": {
                "some_id": "123123"
            },
            "link": {
                "type": "chat",
                "hint": "Dialogue",
                "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
            },
            "message_sender": "customer",
            "client_name": "John Doe",
            "client_phone": "[phone]"
        }))
        .send()?;
        
    Ok(())
}