Sending/importing messages

Method

POST https://amojo.kommo.com/v2/origin/custom/{scope_id}

Description

This method allows you to send incoming and outgoing messages, or import messages that were sent in a third-party application.

The method will create a message and, if necessary, the chat itself for the specified msgid and conversation_id.

Message type	When to use	What parameters should be passed
Incoming from client	the client sent a message to the connected channel	only the payload[sender] field is filled in, the payload[receiver] field is not sent
Outgoing to client from Kommo user	the manager wrote a message to the client, we can identify exactly who sent the message	the fields payload[sender] (information about the manager) and payload[receiver] (information about the client) are filled in, in the field payload[sender][ref_id] the Kommo user ID is passed to the chat API
Outgoing to client from integration bot	the manager wrote a message to the client, we cannot identify who exactly sent the message	the fields payload[sender] (information about the bot) and payload[receiver] (information about the client) are filled in, the ID of the integration bot, which was received when registering the channel in the chat API, is passed to the payload[sender][ref_id] field

Using this API method, you can bulk import old messages into a chat. We recommend performing the import without notifications to managers or creating an incoming lead for all messages except the last one (the most recent).

To do this, you should pass the body parameter payload[silent] a true value for all messages except for the last one that passes the payload[silent] a false value. This way, an incoming message will be created for the last message, and only one notification will come. Thus we will not create unnecessary disturbance for the user.

When importing messages from the integration bot, hooks are not sent.

Headers & Authorization type

The request headers are the same as the ones for all Chat API requests. Information about them is explained in details in the connect a chat channel page.

Header	Description
Date	Date and time when the request was generated.
Content-type	Request data type.
Content-MD5	For the request body
X-Signature	Signature of the request as a string.

Example of the body

{
   "event_type": "new_message",
   "payload": {
       "timestamp": 1670420919,
       "msec_timestamp": 1670420919670,
       "msgid": "f1065e3b-0ec6-427b-b97c-883329acbe3d",
       "conversation_id": "62ef74a4-80c5-403d-93d9-bada6302810d",
       "sender": {
           "id": "b0bc49f0-ec21-4463-965f-1fe1d4cd5a89",
           "avatar": "https://www.w3schools.com/w3images/avatar2.png",
           "profile": {
               "phone": "+18305803077"
           },
           "name": "Adam"
       },
       "receiver": {
           "id": "b0bc49f0-ec21-4463-965f-1fe1d4cd5a90",
           "avatar": "https://www.w3schools.com/w3images/avatar1.png",
           "name": "Lily"
       },
       "message": {
           "type": "text",
           "text": "Hello Lily!"
       },
       "silent": false
   }
}

Body parameters

The body parameter contains the event type with an object called payload.

Parameter	Data type	Description
event_type	string	Event type, currently only new_message is supported
payload	object	An array contains the elements of the message. Description about the elements of the object.

Payload elements

Parameter	Data type	Description
timestamp	int	Message timestamp in the format of Unix Timestamp
msec_timestamp	int	Message timestamp in milliseconds
msgid	string	Chat message ID on the integration side
conversation_id	string	Chat ID on the integration side
conversation_ref_id Optional field	string	Chat ID on Kommo side. Needed to be sent when the client responds to a message sent with “Write first” in order for the Chat API to associate the chat on your side with the chat on the system.
source Optional field	object	Message source. Description about the elements of the object.
sender	object	Message sender. Description about the elements of the object.
receiver	object	Message receiver. Description about the elements of the object.
message	object	An array contains the message components. Description about the elements of the object.
silent	bool	Defines whether the message will trigger a notification in the Kommo account

Source entity

Parameter	Data type	Description
external_id Optional field	string	Chat source identifier on the integration side. The field length is 40 characters, you can use any printable ascii characters and a space.

If you do not need to specify the source, then the source field does not need to be passed.

Message entity

Parameter	Data type	Description
type	string	Message type, one of the following: text, contact, file, video, picture, voice, audio, sticker, location
text	string	The field is mandatory for the “text” type, can be empty for other types
media	string	Url to the file, video, picture, voice, audio, or sticker. Url should be available for download
file_size Optional field	int	The size of the file from the “media” field
file_name	string	The name of the file from the “media” field url, the field is optional. Ignored for the “voice” type
contact	object	Mandatory fields for messages of type contact (contact information). Description about the elements of the object.
location	object	Mandatory fields for messages of type location (geoposition). Description about the elements of the object.

Sender and receiver entities

Parameter	Data type	Description
id Required field	string	Chat participant ID on the integration side
ref_id Optional field	string	Chat participant ID on the Chat API side
name Required field	string	Chat participant name
avatar Optional field	string	Link to the chat participant’s avatar. The link must be available to third-party resources and provide an image for download
profile Optional field	string	Chat participant profile. Description about the elements of the object.
profile_link Optional field	string	Link to the profile of the chat participant in a third-party chat system

Sender and receiver profile

Parameter	Data type	Description
phone Optional field	string	Phone number. When creating an incoming lead, the phone number will be added to the contact data
email Optional field	string	Email address. When creating an incoming lead, the email address will be added to the contact data

Message contact entity

Parameter	Data type	Description
name Required field	string	Conatct name
phone Required field	string	Conatct phone

Message location entity

Parameter	Data type	Description
lon Required field	float	Longitude
lat Required field	float	Latitude

Examples of different bodies

An incoming message from a client

{
   "event_type": "new_message",
   "payload": {
       "timestamp": 1670420919,
       "msec_timestamp": 1670420919670,
       "msgid": "f1065e3b-0ec6-427b-b97c-883329acbe3d",
       "conversation_id": "62ef74a4-80c5-403d-93d9-bada6302810d",
       "sender": {
           "id": "b0bc49f0-ec21-4463-965f-1fe1d4cd5a89",
           "avatar": "https://www.w3schools.com/w3images/avatar2.png",
           "profile": {
               "phone": "+18305803077"
           },
           "name": "Adam"
       },
       "message": {
           "type": "text",
           "text": "Hello Lily!"
       },
       "silent": false
   }
}

An outgoing message from a manager when we can identify the sender

{
   "event_type": "new_message",
   "payload": {
       "timestamp": 1670490330,
       "msec_timestamp": 1670490330161,
       "msgid": "f1065e3b-0ec6-427b-b97c-883329acbe3f",
       "conversation_id": "62ef74a4-80c5-403d-93d9-bada6302810d",
       "sender": {
           "id": "b0bc49f0-ec21-4463-965f-1fe1d4cd5a90",
           "name": "Lama",
           "ref_id": "76fc2bea-902f-425c-9a3d-dcdac4766090"
       },
       "receiver": {
           "id": "b0bc49f0-ec21-4463-965f-1fe1d4cd5a89",
           "avatar": "https://example.com/users/avatar.png",
           "name": "Adam",
           "profile": {
               "phone": "+18305803077",
               "email": "example.client@example.com"
           },
           "profile_link": "https://example.com/profile/example.client"
       },
       "message": {
           "type": "text",
           "text": "Hello from Kommo! It is Thursday already!"
       },
       "silent": true
   }
}

An outgoing message from a manager when we can’t identify the sender (coming from the name of a channel bot)

{
   "event_type": "new_message",
   "payload": {
       "timestamp": 1670490330,
       "msec_timestamp": 1670490330161,
       "msgid": "f1065e3b-0ec6-427b-b97c-883329acbe3f",
       "conversation_id": "62ef74a4-80c5-403d-93d9-bada6302810d",
       "sender": {
           "id": "b0bc49f0-ec21-4463-965f-1fe1d4cd5100",
           "name": "Bot",
           "ref_id": "76fc2bea-902f-425c-9a3d-dcdac47660555"
       },
       "receiver": {
           "id": "b0bc49f0-ec21-4463-965f-1fe1d4cd5a89",
           "avatar": "https://example.com/users/avatar.png",
           "name": "Adam",
           "profile": {
               "phone": "+18305803077",
               "email": "example.client@example.com"
           },
           "profile_link": "https://example.com/profile/example.client"
       },
       "message": {
           "type": "text",
           "text": "Hello from our bot!"
       },
       "silent": true
   }
}

An outgoing message from a manager with media file

{
  "event_type": "new_message",
  "payload": {
      "timestamp": 1670420919,
      "msec_timestamp": 1670420919670,
      "msgid": "f1065e3b-0ec6-427b-b97c-883329acbe3d",
      "conversation_id": "62ef74a4-80c5-403d-93d9-bada6302810d",
       "sender": {
          "id": "b0bc49f0-ec21-4463-965f-1fe1d4cd5a90",
          "name": "Lama",
          "ref_id": "76fc2bea-902f-425c-9a3d-dcdac4766090"
      },
      "receiver": {
          "id": "b0bc49f0-ec21-4463-965f-1fe1d4cd5a89",
          "avatar": "https://example.com/users/avatar.png",
          "name": "Adam",
          "profile": {
              "phone": "+18305803077",
              "email": "example.client@example.com"
          },
          "profile_link": "https://example.com/profile/example.client"
      },
      "message": {
          "type": "file",
          "text": "Please find attached the offer file",
          "media" : "https://www.kommo.com/static/assets/developers/files/examples/offer.pdf",
          "file_name" : "offer"
      },
      "silent": false
  }
}

Example in PHP

$secret = 'fb50586ff7b68cd831fe0ef356345903f644c0d2';
$method = 'POST';
$contentType = 'application/json';
$date =  date(DateTimeInterface::RFC2822);// in format "Wed, 07 Dec 2022 16:00:00 +0000";
$path = '/v2/origin/custom/f62a0162-46a7-430e-b06c-0ef798d56b21_52fd2a28-d2eb-4bd8-b862-a67934927b38';
$url = "https://amojo.kommo.com" . $path;

$body = [
    'event_type' => 'new_message',
    'payload' => [
        'timestamp' => time(),
        'msec_timestamp' => round(microtime(true) * 1000),
        'msgid' => 'f1065e3b-0ec6-427b-b97c-883329acbe3d',
        'conversation_id' => '62ef74a4-80c5-403d-93d9-bada6302810d',
        'sender' => [
            'id' => 'b0bc49f0-ec21-4463-965f-1fe1d4cd5a89',
            'avatar' => 'https://www.w3schools.com/w3images/avatar2.png',
            'profile' => [
                'phone' => '+18305803077',
            ],
            'name' => 'Adam',
        ],
        'message' => [
            'type' => 'text',
            'text' => 'Hello Kommo!',
        ],
        'silent' => false,
    ],
];

$requestBody = json_encode($body);
$checkSum = md5($requestBody);

$str = implode("\n", [
    strtoupper($method),
    $checkSum,
    $contentType,
    $date,
    $path,
]);
$signature = hash_hmac('sha1', $str, $secret);

$headers = [
    'Date' => $date,
    'Content-Type' => $contentType,
    'Content-MD5' => strtolower($checkSum),
    'X-Signature' => strtolower($signature),
];

$curlHeaders = [];
foreach ($headers as $name => $value) {
    $curlHeaders[] = $name . ": " . $value;
}

echo $method . ' ' . $url . PHP_EOL;
foreach ($curlHeaders as $header) {
    echo $header . PHP_EOL;
}
echo PHP_EOL . $requestBody . PHP_EOL;

Example of the cURL request

curl --location --request POST 'https://amojo.kommo.com/v2/origin/custom/f62a0162-46a7-430e-b06c-0ef798d76a21_52fd2a28-d2eb-4bd8-b862-a67934927b38' \
--header 'Date: Wed, 07 Dec 2022 16:00:00 +0000' \
--header 'Content-Type: application/json' \
--header 'Content-MD5: fd1582fbc028bf3c3752ab4ecba1aafd' \
--header 'X-Signature: fb50ad5e1b0bcf52c0072bb021944fa394104704' \
--data-raw '{"event_type":"new_message","payload":{"timestamp":1670421428,"msec_timestamp":1670421428210,"msgid":"f1065e3b-0ec6-427b-b97c-883329acbe3d","conversation_id":"62ef74a4-80c5-403d-93d9-bada6302810d","sender":{"id":"b0bc49f0-ec21-4463-965f-1fe1d4cd5a89","avatar":"https://www.w3schools.com/w3images/avatar2.png",   "profile":{"phone":"+18305803077"},"name":"Adam"},"message":{"type":"text","text":"Hello Kommo!"},"silent":false}}'

Data type header when the request is successful

Content-Type: application/json

Data type header in case of an error

Content-Type: application/json

HTTP response codes

Response code	Case
200	The message is accepted for processing.
403	Incorrect request signature.
400	Invalid data are given. Details are available in the response.

Response

{
   "new_message": {
       "msgid": "7465c4de-47b3-43ed-b46e-db12b688482f",
       "ref_id": "f1065e3b-0ec6-427b-b97c-883329acbe3d"
   }
}

Response parameters

The method returns the amojo_id of the message that will appear in the chat feed when processed.

Parameter	Data type	Description
new_message[msgid]	string	Message ID in the Chats API
new_message[ref_id]	string	Chat ID on the integration side

Now, let retrieve the chat history.