Отправка сообщений

Для отправки сообщений из персонального канала, используйте следующий метод:

Метод	POST
Адрес	https://api.suvvy.ai/api/webhook/custom/message

Заголовки

Заголовок	Значение
Authorization	Bearer <токен>
Content-Type	application/json

При запросе необходимо передать токен, полученный при подключении канала.

Тело запроса

{
  "api_version": 1,
  "message_id": "<ID_сообщения>",
  "chat_id": "<ID_чата>",
  "text": "Привет!",
  "attachments": [
    {
      "file_name": "файл.png",
      "file_type": "image",
      "data": "aHR0cHM6Ly93d3cueW91dHViZS5jb20vd2F0Y2g/dj1kUXc0dzlXZ1hjUQ=="
    }
  ],
  "source": "Иванов Иван из Авито",
  "placeholders": {
     "some_id": "123123"
  },
  "link": {
    "type": "chat",
    "hint": "Диалог",
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  },
  "message_sender": "customer",
  "client_name": "Иванов Иван",
  "client_phone": "[phone]"
}

Поле	Поле обязательно	Тип	Описание
api_version	да	целое число (только 1)	Версия API. В будущем мы будем обновлять наше API, и чтобы у вас ничего не сломалось, какое-то время будем параллельно поддерживать и старые версии.
message_id	да	строка	ID сообщения в вашей системе. Необходимо для предотвращения случайных повторных срабатываний
chat_id	да	строка	ID чата в вашей системе. Связывающая часть, определяет в какой диалог попадет сообщение
text	да, если не указано поле attachments	строка, не меньше 1 символа	Текст сообщения.
attachments	да, если не указано поле text	массив объектов Attachment	Вложения. На данный момент поддерживаются только картинки и аудио
message_sender	да	строка (customer или employee)	Отправитель сообщения. Клиент или сотрудник из вашей системы
source	да	строка	Источник. Значение, которое показывается в колонке "Источник" в личном кабинете Савви. Как правило - имя или юзернейм клиента, название сделки
link	нет	объект Link	Ссылка на чат в вашей системе. Будет отображаться как кнопка в личном кабинете Савви
placeholders	нет	объект, где ключ и значение - строки	Переменные для инструкции. Подробнее ниже
client_name	нет	строка	Имя клиента.
client_phone	нет	строка	Номер телефона клиента.

Переменные

Объект Attachment

Все поля обязательны.

Поле	Тип	Описание
file_name	строка	Имя файла.
file_type	строка (image или audio)	Тип файла.
data	строка, base64 файла	Файл. Допустимые типы указаны ниже.

Савви принимает файлы следующих типов:

• Для изображений: image/png, image/jpeg, image/gif

• Для аудио: audio/ogg, audio/mpeg, audio/wav, audio/x-wav, audio/webm, audio/mp4, audio/m4a, audio/x-m4a

Максимальный размер файла - 15 мегабайт

Объект Link

Поле	Тип	Описание
type	строка (user, chat, phone, lead, product, other)	Тип ссылки. Влияет на иконку, отображаемую в личном кабинете user - 👤 chat - 💬 phone - 📞 lead - 🤝🏻 product - 🛍️ other - 🔗
hint	строка или null	Текст для кнопки. Не обязательно. Если не указано (или null), то используются названия, взависимости от типа: user - Аккаунт chat - Чат phone - Телефон lead - Лид product - Товар other - Ссылка
url	строка	Ссылка.

Ответ

При успехе вебхук возвращает тело следующего вида:

{
  "message": "Successful"
}

Его можно игнорировать, оно не несет никакой полезной информации.

Ошибки

Неверный токен

Вернет тело следующего вида и код 401:

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

Канал отключен

Возвращается, если канал не подключен или выключен в настройках. Вернет тело следующего вида и код 424:

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

Неподдерживаемый тип файла

Возвращается, если переданный файл не поддерживается Савви. Возвращает поддерживаемые типы. Вернет тело следующего вида и код 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"
  ]
}

Отрицательный баланс

Возвращается, если ваш баланс Савви меньше нуля. Вернет тело следующего вида и код 402:

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

Ошибка валидации

Возвращает код 422 и тело, в котором подробно описано, что было передано не так.

Пример кода для отправки

Python (requests)

import requests

response = requests.post(
    'https://api.suvvy.ai/api/webhook/custom/message',
    headers={
        'Authorization': 'Bearer ваш_токен',
        'Content-Type': 'application/json'
    },
    json={
        'api_version': 1,
        'message_id': 'уникальный_айди_сообщения',
        'chat_id': 'уникальный_айди_чата',
        'text': 'Привет!',
        'attachments': [
            {
                'file_name': 'файл.png',
                'file_type': 'image',
                'data': 'base64_данные_файла'
            }
        ],
        'source': 'Иванов Иван из Авито',
        'placeholders': {
            'some_id': '123123'
        },
        'link': {
            'type': 'chat',
            'hint': 'Диалог',
            'url': 'https://www.youtube.com/watch?v=dQw4w9WgXcQ'
        },
        'message_sender': 'customer',
        'client_name': 'Иванов Иван',
        'client_phone': '[phone]'
    }
)

JavaScript (fetch)

fetch('https://api.suvvy.ai/api/webhook/custom/message', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer ваш_токен',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        api_version: 1,
        message_id: 'уникальный_айди_сообщения',
        chat_id: 'уникальный_айди_чата',
        text: 'Привет!',
        attachments: [
            {
                file_name: 'файл.png',
                file_type: 'image',
                data: 'base64_данные_файла'
            }
        ],
        source: 'Иванов Иван из Авито',
        placeholders: {
            some_id: '123123'
        },
        link: {
            type: 'chat',
            hint: 'Диалог',
            url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ'
        },
        message_sender: 'customer',
        client_name: 'Иванов Иван',
        client_phone: '[phone]'
    })
})

PHP (cURL)

$ch = curl_init('https://api.suvvy.ai/api/webhook/custom/message');
$data = [
    'api_version' => 1,
    'message_id' => 'уникальный_айди_сообщения',
    'chat_id' => 'уникальный_айди_чата',
    'text' => 'Привет!',
    'attachments' => [
        [
            'file_name' => 'файл.png',
            'file_type' => 'image',
            'data' => 'base64_данные_файла'
        ]
    ],
    'source' => 'Иванов Иван из Авито',
    'placeholders' => [
        'some_id' => '123123'
    ],
    'link' => [
        'type' => 'chat',
        'hint' => 'Диалог',
        'url' => 'https://www.youtube.com/watch?v=dQw4w9WgXcQ'
    ],
    'message_sender' => 'customer',
    'client_name' => 'Иванов Иван',
    'client_phone' => '[phone]'
];
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ваш_токен',
    '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);
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
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 ваш_токен',
  'Content-Type' => 'application/json'
}
data = {
  api_version: 1,
  message_id: 'уникальный_айди_сообщения',
  chat_id: 'уникальный_айди_чата',
  text: 'Привет!',
  attachments: [
    {
      file_name: 'файл.png',
      file_type: 'image',
      data: 'base64_данные_файла'
    }
  ],
  source: 'Иванов Иван из Авито',
  placeholders: {
    some_id: '123123'
  },
  link: {
    type: 'chat',
    hint: 'Диалог',
    url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ'
  },
  message_sender: 'customer',
  client_name: 'Иванов Иван',
  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 ваш_токен")
        .header("Content-Type", "application/json")
        .json(&json!({
            "api_version": 1,
            "message_id": "уникальный_айди_сообщения",
            "chat_id": "уникальный_айди_чата",
            "text": "Привет!",
            "attachments": [
                {
                    "file_name": "файл.png",
                    "file_type": "image",
                    "data": "base64_данные_файла"
                }
            ],
            "source": "Иванов Иван из Авито",
            "placeholders": {
                "some_id": "123123"
            },
            "link": {
                "type": "chat",
                "hint": "Диалог",
                "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
            },
            "message_sender": "customer",
            "client_name": "Иванов Иван",
            "client_phone": "[phone]"
        }))
        .send()?;

    Ok(())
}