Description

🚧
Please be aware that you won't be able to execute this step described above directly in the API Reference section due to tool limitations: it is not possible to calculate required headers and send a request simultaneously

Send/import a message

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

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

Message type Use case Parameters that should be passed

Message type	Use case	Parameters that should be passed
Incoming from: client	A client sends a message to the connected channel	Only the `payload[sender]` field is filled in, the `payload[receiver]` field is not sent
Outgoing from: Kommo user to: client	A manager writes a message to the client, we can identify who sends the message	The fields `payload[sender]`(information about the manager) and `payload[receiver]`(information about the client) are filled in. `amojo_id` of the user is passed to `payload[sender][ref_id]` (you can get it via GET users list request applying`?with=amojo_id` query parameter).
Outgoing from: integration bot to: client	A manager writes a message to the client, we can't identify who sends the message	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.

Incoming

from: client

A client sends a message to the connected channel

Only the payload[sender] field is filled in, the payload[receiver] field is not sent

Outgoing

from: Kommo user
to: client

A manager writes a message to the client, we can identify who sends the message

The fields payload[sender](information about the manager) and payload[receiver](information about the client) are filled in. amojo_id of the user is passed to payload[sender][ref_id] (you can get it via GET users list request applying?with=amojo_id query parameter).

Outgoing

from: integration bot
to: client

A manager writes a message to the client, we can't identify who sends the message

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 lead will be created for the last message, and only one notification will come. Thus we will not create unnecessary disturbance for the user.

{
  "event_type": "new_message",
  "payload": {
    "timestamp": 1639604761,
    "msec_timestamp": 1639604761694,
    "msgid": "my_int-5f2836a8ca475",
    "conversation_id": "my_int-d5a421f7f217",
    "sender": {
      "id": "my_int-1376265f-86df-4c49-a0c3-a4816df41af8",
      "avatar": "https://example.com/users/avatar.png",
      "profile": {
        "phone": "+1400000000",
        "email": "[email protected]"
      },
      "profile_link": "https://example.com/profile/example.client",
      "name": "Client name"
    },
    "message": {
      "type": "text",
      "text": "Message from a client"
    },
    "silent": false
  }
}

{
  "event_type": "new_message",
  "payload": {
    "timestamp": 1639604903,
    "msec_timestamp": 1639604903161,
    "msgid": "my_int-5f2836a8ca476",
    "conversation_id": "my_int-d5a421f7f217",
    "sender": {
      "id": "my_int-manager1_user_id",
      "name": "Manager name",
      "ref_id": "76fc2bea-902f-425c-9a3d-dcdac4766090"
    },
    "receiver": {
      "id": "my_int-1376265f-86df-4c49-a0c3-a4816df41af8",
      "avatar": "https://example.com/users/avatar.png",
      "name": "Client name",
      "profile": {
        "phone": "+1400000000",
        "email": "[email protected]"
      },
      "profile_link": "https://example.com/profile/example.client"
    },
    "message": {
      "type": "text",
      "text": "Message from a manager 76fc2bea-902f-425c-9a3d-dcdac4766090"
    },
    "silent": true
  }
}

{
  "event_type": "new_message",
  "payload": {
    "timestamp": 1639605194,
    "msec_timestamp": 1639605194102,
    "msgid": "my_int-5f2836a8ca477",
    "conversation_id": "my_int-d5a421f7f217",
    "sender": {
      "id": "my_int-bot_user_id",
      "name": "Bot",
      "ref_id": "f1910c7f-b1e0-4184-bd09-c7def2a9109a"
    },
    "receiver": {
      "id": "my_int-1376265f-86df-4c49-a0c3-a4816df41af8",
      "avatar": "https://example.com/users/avatar.png",
      "name": "Client name",
      "profile": {
        "phone": "+1400000000",
        "email": "[email protected]"
      },
      "profile_link": "https://example.com/profile/example.client"
    },
    "message": {
      "type": "text",
      "text": "Message from the channel bot f1910c7f-b1e0-4184-bd09-c7def2a9109a"
    },
    "silent": true
  }
}

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

Send a comment

The method also allows you to transfer incoming and outgoing comments (responses to comments that were sent in a third-party application).

The main difference between sending comments and sending messages is the addition of a post field to the request, which contains the post ID on the integration side.

{
    "event_type": "new_message",
    "payload": {
        "timestamp": 1639604761,
        "msec_timestamp": 1639604761694,
        "msgid": "my_int-5f2836a8ca475",
        "conversation_id": "my_int-d5a421f7f217",
        "sender": {
            "id": "my_int-1376265f-86df-4c49-a0c3-a4816df41af8",
            "avatar": "https://example.com/users/avatar.png",
            "profile": {
                "phone": "+1234567890",
                "email": "[email protected]"
            },
            "profile_link": "https://example.com/profile/example.client",
            "name": "Client name"
        },
        "message": {
            "type": "text",
            "text": "Message from the client",
            "post": {
                "id": "my-int-376265",
                "url": "https://www.example.com/@example/video/7490",
                "preview_url": "https://example/1/preview.png",
                "preview_permalink": "https://example/2/preview.png",
                "username": "post creator",
                "caption": "Post description"
            }
        },
        "silent": false
    }
}

{
    "event_type": "new_message",
    "payload": {
        "timestamp": 1639604903,
        "msec_timestamp": 1639604903161,
        "msgid": "my_int-5f2836a8ca476",
        "conversation_id": "my_int-d5a421f7f217",
        "sender": {
            "id": "my_int-manager1_user_id",
            "name": "Manager name",
            "ref_id": "76fc2bea-902f-425c-9a3d-dcdac4766090"
        },
        "receiver": {
            "id": "my_int-1376265f-86df-4c49-a0c3-a4816df41af8",
            "avatar": "https://example.com/users/avatar.png",
            "name": "Client name",
            "profile": {
                "phone": "+1234567890",
                "email": "[email protected]"
            },
            "profile_link": "https://example.com/profile/example.client"
        },
        "message": {
            "type": "text",
            "text": "Comment from a manager 76fc2bea-902f-425c-9a3d-dcdac4766090",
            "post": {
                "id": "my-int-376265",
                "url": "https://www.example.com/@example/video/7490",
                "preview_url": "https://example/1/preview.png",
                "preview_permalink": "https://example/2/preview.png",
                "username": "post creator",
                "caption": "Post description"
            }
        },
        "silent": true
    }
}

The method will create a comment and if necessary the chat itself for the specified msgid and conversation_id respectively. Comments will be created in the same chat with personal messages, but in different conversations. A conversation will be created containing all comments from the client for each commented post. The structure of the receiver and sender fields is the same for importing a common message.

Edit a message

The method also allows you to edit messages sent to your clients. You need to pass event_type: edit_message in the message payload.

{
  "event_type": "edit_message",
  "payload": {
    "timestamp": 1639605194,
    "msec_timestamp": 1639605194102,
    "msgid": "my_int-5f2836a8ca477",
    "conversation_id": "my_int-d5a421f7f217",
    "message": {
      "type": "text",
      "text": "Edited message"
    }
  }
}

Headers & Authorization type

Parameter	Data type	Description
Date	string	Date and time when the request was generated. The signature will be valid for 15 minutes from this Date. The date should be in the format `Thu, 01 Jan 2023 12:00:00 +0000` (RFC2822)
Content-type	string	Request data type. Currently, only application/json is supported.
Content-MD5	string	For the request body, it is necessary to calculate the MD5 hash and indicate it in the header in lowercase. At the same time, it is important to keep in mind that the request body is calculated as a stream of bytes without considering the end of JSON markup, and if there are “\n” or spaces at the end, they will also be taken into account.
X-Signature	string	Signature of the request as a string. It is formed from the name of the method (GET/POST) in uppercase, with the values of the headers concatenated by “\n”. Header values come in a specific order. If there is no header, an empty string is specified instead. Next, add the requested path from the URL without the protocol and domain (without GET parameters) to the line. The resulting string is calculated using HMAC-SHA1, and as a secret, we use the channel secret obtained during registration. The resulting hash in lowercase is indicated in the X-Signature header.

Data type header when the request is successful/in case of an error

Content-Type: application/json

Response parameters

Parameter	Date type	Description
new_message[msgid]	string	Message ID in the Chats API
new_message[ref_id]	string	Message ID on the integration side
new_message[conversation_id]	string	Chat ID in the Chats API
new_message[sender_id]	string	Message sender ID in the Chats API
new_message[receiver_id]	string	Message receiver ID in the Chats API

Import, send and edit messages

Description

Send/import a message

Send a comment

Edit a message

Headers & Authorization type

Response parameters

What’s Next

What’s Next

Description

Send/import a message

Send a comment

Edit a message

Headers & Authorization type

Response parameters

200200

400400

403403

What’s Next

What’s Next