Starting the work
First of all, let’s express our happiness that you entered this part of our documentation and tell you how excited we are to introduce you to the opportunities you can have by integrating your best messenger with Kommo!
Our goal from this part is to create a messenger integration that will connect Kommo accounts with a messenger application using our Chat API and the desired messenger way of communication.
Messaging integrations with Kommo use our online chat system, amojo, which manages to send and receive messages using queues. It’s better if the integration uses a queue to handle the load. Sending messages from/to Kommo is done using our Chat API, while sending/receiving messages to the chat service is done by its way.
The system has essential and auxiliary entities, which can be linked to each other, and all entities can be accessed using API.
- Account: It represents the company in which the business is being managed. The account id we are considering here is the account id in Kommo online chats.
- User: A person who works in the company represented by the account. Users can be administrators or managers. Administrators can install integrations, while you, integrators, can decide what permission the user should have to set up and work with the integration. The user id taken into account when working in chats is the user id in Kommo online chats.
- Pipeline: A visual representation of all sales cycles. Administrators can create multiple pipelines and assign each one for a specific purpose, and then users add leads to each pipeline according to its goal.
- Lead: It represents a sale. The entity Lead consists of a predefined set of fields and additional fields created by the account administrator. Each lead can be attached to one or more contacts or not linked to any, and it can be attached to only one company.
- Sources: The sources from where the potential customers come. Each source can represent a purpose in our chat subject area, and the created incoming leads go to the corresponding pipeline.
- Incoming leads: These are leads that initiate contact through managers’ connected channels like chat integrations, considered Lead sources. When a lead tries to connect you through a specific chat channel, they will come to the Incoming lead’s stage in the associated pipeline. The manager can decide to accept if it is a potential customer or decline if it is spam.
- Contact: It represents a person with contact information participating in leads. It consists of a predefined set of fields and additional ones created by the account administrator. Each contact may participate in one or more leads or may not be associated with any, can be attached to one company and can be assigned a responsible user.
- Company: Similar to the entity Contact. It consists of predefined fields and additional ones created by the account administrator. Each company may participate in one or more leads or may not associate with any. Each company can be assigned a responsible user.
Chats in Kommo
- Chat channel: The messaging service in a Kommo account.
- Conversation: A chat between a client and Kommo users, which can be displayed in the client card or lead.
- Message: An individual media (text/image/video..) in a conversation.
- Chat templates: A pre-made message can be prepared to reply to clients and can be used in the cards and bots. They contain placeholders that can be replaced with the client’s info and situation.
- Webhooks: Each account in Kommo can report various events to a third-party web server using webhooks. In Kommo chats, webhooks are used as a notifier when sending a message from Kommo to the contact.
For more about the API methods.
You can also read about these and other definitions in the Kommo subject area.
Familiarize yourself with Kommo Chat API
- Connecting chat channel: connect the chat channel to the account.
- Creating a new chat: create a new chat before sending the first message. It can be helpful if a lead with the contact exists, and creating an incoming lead is optional.
- Linking chat to contact: link an existing chat to a contact.
- Incoming messages: get information about the message from the chat service, recieve the incoming messages in the Kommo account using our API, or import messages sent in a third-party application.
- Outgoing message: send a message from Kommo to the chat service and get webhook information, or import an outgoing message and add its information in kommo using our API.
- Getting chat history: get a list of messages in a specific chat.
- Update delivery status: update the delivery status of a specific message.
- Typing Information: add information that the client is currently typing something in the messenger in the Kommo interface.
- Disconnecting chat channel: send a request to disconnect the chat channel and, therefore, stop receiving webhooks for outgoing messages.
For more information about our Chat API capabilities.
You need to determine the functions you want to provide from your service, such as authorizing users in your service, sending and receiving messages, changing the message status, sending typing status, etc. Also, you should provide communication methods with Kommo to send notifications and events.
You could take into account these points about your messenger service API:
- is sending a message different from receiving one
- does your messenger change the status of a message when delivered, read, or failed
- is it possible to get the history of a chat
- does your messenger provide rich media messages
- is there a limitation on writing to the client first
- does your messenger provide a social profile for the client
Now we should get to know the use cases we need to consider.