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

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

Метод

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": "+79001234567"
}

Поле

Поле обязательно

Тип

Описание

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 и тело, в котором подробно описано, что было передано не так.

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

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': '+79001234567'
    }
)

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: '+79001234567'
    })
})

$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' => '+79001234567'
];
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);

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: '+79001234567'
}

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)

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": "+79001234567"
        }))
        .send()?;

    Ok(())
}

PreviousПерсональный канал (API)NextПолучение сообщений

Last updated 9 months ago

Was this helpful?

hashtagЗаголовки

hashtagТело запроса

hashtagОбъект Attachment

hashtagОбъект Link

hashtagОтвет

hashtagОшибки

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

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

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

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

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

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

Заголовки

Тело запроса

Объект `Attachment`

Объект `Link`

Ответ

Ошибки

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

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

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

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

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

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