Conversations

Current section covers methods, provided in order to work with conversation entities.

Contents

Obtain a conversation by ID

Method

GET /api/v4/talks/{id}

Description

Method allows to obtain data for a specific conversation by its ID.

Limitations

Method is available for every user of an account. Data returned varies depending on permissions, set for contact the conversation belongs to.

Response header in case of a success

Content-Type: application/hal+json

Response header in case of an error

Content-Type: application/problem+json

HTTP response codes

Response code Condition
200 The request succeeded
401 User is unauthorized
402 Account is unpaid
403 Forbidden
404 Conversation not found

Response fields

Method returns a conversation model, fields of which are listed below.

Field Data type Description
talk_id int Conversation ID
created_at int Conversation creation date, represented by Unix Timestamp
updated_at int Conversation update date, represented by Unix Timestamp
rate int Customer conversation rating, set as a result of processing by NPS bot
contact_id int ID of a contact the conversation belongs to
chat_id string ID of a chat the conversation belongs to
entity_id int|null ID of an entity the conversation is about
entity_type string|null Type of an entity the conversation is about (lead, customer)
is_in_work bool Is conversation being processed (not closed)
is_read bool Has conversation been read
origin string Type of a source the conversation was created for (Telegram, Viber, etc.)
missed_at int|null Date, when conversation was missed (no response in the time bounds, set in the account settings), represented by Unix Timestamp
account_id int Account ID
_embedded object Embedded entities data
_embedded[contacts] array Data of contacts the conversation belongs to (no more than one)
_embedded[contacts][0] object Model of a contact the conversation belongs to
_embedded[contacts][0][id] int ID of a contact the conversation belongs to
_embedded[leads] array Data of deals the conversation is about (no more than one)
_embedded[leads][0] object Model of a deal the conversation is about
_embedded[leads][0][id] int ID of a deal the conversation is about
_embedded[customers] array Data of customers the conversation is about (no more than one)
_embedded[customers][0] object Model of a customer the conversation is about
_embedded[customers][0][id] int ID of a customer the conversation is about

Response example

        
{
    "talk_id": 117,
    "created_at": 1631018291,
    "updated_at": 1631035929,
    "rate": 0,
    "contact_id": 3372695,
    "chat_id": "88278e98-2b8d-4ae2-a5f0-bfab511cd621",
    "entity_id": 667999637,
    "entity_type": "lead",
    "is_in_work": true,
    "is_read": true,
    "origin": "telegram",
    "missed_at": null,
    "account_id": 17029541,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/talks/117"
        }
    },
    "_embedded": {
        "contacts": [
            {
                "id": 3372695,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/contacts/3372695"
                    }
                }
            }
        ],
        "leads": [
            {
                "id": 667999637,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/leads/667999637"
                    }
                }
            }
        ],
        "customers": []
    }
}
        
    

Close a conversation by ID

Method

POST /api/v4/talks/{id}/close

Description

Method allows to launch a NPS bot or close a conversation by its ID.
NPS bot is being launched only when, then it is enabled in the account settings, is available in a tariff plan and no force_close parameter is supplied.

Limitations

Method availability depends on user permissions for contact the conversation belongs to.

Request header

Content-Type: application/json

Request fields

In order to close a conversation without a NPS bot launch it is required to pass a force_close parameter with value of true.

Field Data type Description
force_close bool Forcefully close a conversation, optional, defaults to false

Request example

In the following example we’ll forcefully close a conversation.

        
{
    "force_close": true
}
        
    

HTTP response codes

Response code Condition
202 The request succeeded
401 User is unauthorized
402 Account is unpaid
403 Forbidden
404 Conversation not found
422 Conversation has already or are being closed

Response fields

Method has no response fields.