A Kommo oferece aos desenvolvedores a capacidade de integrar diversos canais de mensagens. Para os usuários, a experiência de interação com esses canais através da interface do Kommo será contínua, semelhante aos canais existentes, como WhatsApp, Facebook e Telegram.
Por favor, esteja ciente de que você precisa criar um canal de chat e continuar com a API de Chats somente se estiver desenvolvendo sua própria integração com um mensageiro.
Este artigo irá guiá-lo pelos passos básicos necessários para começar a desenvolver uma integração com a API de Chat.
Para iniciar o desenvolvimento, você precisará de:
- Uma conta ativa no Kommo. Você pode se inscrever para um teste gratuito.
- Um endpoint público no seu servidor onde as notificações de novas mensagens serão recebidas pela interface do Kommo.
- Um canal de chat registrado para ser usado com a API de Chat.
Solicitar um novo canal
Na Kommo, a API de Chat é responsável por gerenciar chats, canais e mensagens.
Por padrão, um canal no Kommo refere-se a um tipo específico de plataforma de chat, como WhatsApp, Viber, Facebook ou um chat online em um site. Ele facilita a troca de mensagens entre o Kommo e a respectiva plataforma de chat por meio da integração.
Para registrar um canal para chats via API, você precisa enviar uma solicitação ao suporte técnico da Kommo.
Sua solicitação deve conter:
| Listar item | Obrigatório? | Descrição |
|---|---|---|
| 1. Nome do serviço | ✅ | O nome do serviço para o qual você planeja desenvolver a integração. Este nome será exibido junto com o ícone SVG no perfil social, sob o nome do contato criado usando este canal de chat. Certifique-se de que o nome do serviço contenha apenas caracteres latinos e não comece com um número. |
| 2. URL do Webhook | ✅ | A URL do webhook para onde o Kommo enviará mensagens deve estar no formato https://domain.com/location/:scope_id. O marcador scope_id será definido dinamicamente pelo sistema e pode ser usado para identificar a conta da qual a mensagem veio. |
| 3. ID da conta Kommo | ✅ | Um ID da conta do Kommo que funcionará com o novo canal. |
| 4. Recurso Escrever Primeiro | ❌ | Para usar o recurso Escrever primeiro, você pode precisar utilizar modelos para garantir uma experiência de alta qualidade e minimizar mensagens de spam. |
| 5. Time Window | ✅ | Devido ao fato de que muitas integrações limitam a capacidade de enviar mensagens após um determinado período, adicionamos suporte para Janelas de Tempo. A própria integração determina a duração da Janela de Tempo. No perfil, após cada mensagem recebida, o cronômetro será redefinido e contará o tempo restante até o final da Janela. Uma integração também pode indicar que precisa bloquear o controle de envio de mensagens após a expiração da Janela. Quando o controle de envio é bloqueado, o usuário ainda terá a opção de selecionar um modelo para envio. Portanto, se você precisar de uma Janela de Tempo: 5.1 Você deve fornecer a duração da janela em segundos e 5.2 Escolher se os modelos de chat serão exibidos após a expiração da Janela de Tempo. |
| 6. Email | ✅ | E-mail para comunicação em caso de problemas. |
| 7. Ícone SVG | ✅ | Ícone SVG do seu canal. O ícone deve ser redondo ou ajustado para esse formato, com tamanho de 14x14px. |
| 8. ID da integração | ✅ | ID da integração que funcionará com a API de Chat. Primeiro, você deve criar uma integração, e o ID da integração pode ser obtido na aba Chaves nas propriedades da integração. |
| 9. Código do widget de integração | ✅ | Código do widget de integração que funcionará com a API de Chat e as fontes de API. A integração criada deve conter um widget. Para integrações públicas, a chave do widget é definida pelo integrador e também pode ser copiada da aba “Minhas submissões” na página de configurações/integrações. Para integrações privadas, ela pode ser obtida na aba de chaves nas propriedades da integração. |
| 10. Privado/público | ✅ | Você planeja publicar sua solução para todos os usuários da Kommo? Já existe uma solução semelhante no Kommo? Se houver, o que torna sua solução única? |
| 11. Avançado A integração armazena arquivos? | ❌ | É necessário determinar se a integração armazena arquivos em seu lado que são enviados para a API de Chat do Kommo. Essa configuração afeta o comportamento da funcionalidade de upload atrasado. O arquivo deve ser acessível via o link enviado no webhook. |
| 12. Avançado A integração suporta reações? | ❌ | Se a integração oferecer suporte a determinadas reações, forneça-as no formato: 👍😳. |
| 13. Avançado A integração suporta citação de mensagens? | ❌ | O recurso de citação de mensagens permite que os usuários façam referência a mensagens específicas em uma conversa. |
| 14. Avançado A integração suporta mensagens de voz? | ❌ | O suporte a mensagens de voz permite que os usuários enviem e recebam mensagens de áudio em vez de texto. |
| 15. Avançado Qual é o tamanho máximo de arquivo disponível para enviar no chat? | ❌ | Se seu chat oferecer suporte para compartilhamento de arquivos, informe o tamanho máximo de arquivo permitido para este canal de chat. |
A equipe de Suporte Técnico da Kommo analisa as solicitações em 1 a 3 dias úteis.
Em resposta, nosso Suporte Técnico fornecerá os parâmetros para acessar a API de Chat e os parâmetros do bot do canal registrado.
NÃO recomendamos conectar mais de um canal de chat a uma integração. Se você conectar mais de um, poderá enfrentar implicações inesperadas.
Exemplo da resposta
{
"result": {
"en": {
"id": "dw2asda2-929f-47c3-b1e7-c845a941833b",
"code": "Codechat",
"secret_key": "1eqadw323ead22wW2E1SA",
"name": "Chat",
"webhook_url": "https://webhook.site/4e6a83e5-90d02-4212192c-9c6d-adwdas212",
"enabled": true,
"test_mode": true,
"allowed_acc_list": [
{
"id": "1232d-d75c-4ee0-2dasd3-21easda212",
"external_id": "kommo:1234567"
}
],
"contact_email": "[email protected]",
"created_at": 1732273375,
"updated_at": 1732273375,
"widget_code": "sadedf234fdq2easd2312sdws",
"supports_reply": true,
"write_first": true,
"webhook_url_v2": "https://webhook.site/4e6a83e5-90d02-4212192c-9c6d-adwdas212",
"time_window": {
"enabled": true,
"expires": 100000,
"tags": null,
"need_template": true
},
"bot": {
"id": "adads312-7ad01b-asdw3d23-das213-243r513sa",
"name": "Chat",
"is_bot": true
},
"webhook_events": [
"messages",
"typing"
],
"saves_files": true,
"supports_voice": true,
"supports_delivery_notification": true,
"icon": "https://st1.kommo.com/origins_icons/Chat.svg?1732273375",
"webhook_v2": true,
"time_window_support": true,
"need_display_template": true,
"time_window_enum": 100000,
"reactions_all": true,
"reactions_list": "",
"picture_size": 2,
"video_size": 2,
"voice_size": 2,
"file_size": 2,
"opposite_platform_enabled": false,
"client_uuid": "adwdasd2-21e2sdd-40ee-2dasd21-21e21e2esa"
}
},
"error": null
}
Exemplo de credenciais de acesso para chats online
| Parâmetro | Exemplo |
|---|---|
| Código do canal | amo.ext.12345678 |
| ID do canal | 1234567-12be-4sr6-qwe3-0r12345446t201 |
| Canal secreto | 12345678supersecret1234567 |
| Uma conta conectada ao canal | 12345678 |
Parâmetros do Bot do canal registrado como exemplo
| Parâmetr | Tipo de dado | Descrição | Exemplo |
|---|---|---|---|
| id | string | ID do participante do chat no lado da Kommo (amojo_id) | 55c5555a-5ad5-4555-a555-555d55b5e5b5 |
| client_id | string | ID do participante do chat no lado da integração | 987654321-48d75-r4c89nt7-9ct4c |
| name | string | Nome do bot | MyKommo |
Após a implementação da integração, ela pode ser publicada em nosso Marketplace assim que passar pela moderação. Isso permitirá que ela seja conectada a outras contas.
Se o canal estiver conectado a uma integração privada, ele estará acessível apenas para a conta especificada na solicitação.