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

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

Link object

Link to chat in your system. Will be displayed as a button in the Suvvy dashboard.

placeholders

object, where key and value are strings

Variables for instructions. More details below.

client_name

string

Client name.

client_phone

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

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

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

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

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

PreviousWorking with webhook NextYCLIENTS

Last updated 1 month ago

Headers

Request Body

Attachment Object

Link Object

Response

Errors

Invalid Token

Channel Disabled

Unsupported File Type

Negative Balance

Validation Error

Code Examples

`Attachment` Object

`Link` Object