Session Link

API para desenvolvedores

Obtenha um link direto para a conversa de um cliente a partir dos seus próprios sistemas; o cliente e a conversa são criados se ainda não existirem.

• WhatsApp
• Instagram
• REST API

Instalar pela MonoStoreVer em monochat.ai

Visão geral

Uma chamada de API com um canal e o telefone ou e-mail de um cliente retorna um link que abre a conversa desse cliente no MonoChat. Se o cliente ou a conversa ainda não existir, eles são criados.

Coloque o link no seu CRM, help desk ou tela de pedidos e a sua equipe vai direto dali para o chat.

Destaques

• Abrir ou criar. Funciona para um cliente em um determinado canal de WhatsApp, Instagram ou outro, por telefone ou e-mail.
• Roteie no caminho. Atribua a conversa a um atendente, por id ou e-mail, ou a um grupo de trabalho na mesma chamada.
• Mesmo cliente, mesma conversa. Chamar de novo para o mesmo cliente e canal retorna a conversa existente.

Instalação e configuração

1. Instale o Session Link em Configurações › MonoStore › Aplicativos, ou abra o link de instalação app.monochat.ai/apps/vvKJe8Nbp4EQNy2KA. Se você ainda não tem uma conta MonoChat, o link permite que você se cadastre primeiro e instala o app para você.
2. Crie um token de API em Perfil › Tokens de API. O token é exibido apenas uma vez, então copie-o imediatamente. Veja Tokens de API.
3. Abra Configurações › Session Link API. A documentação ali mostra o endereço exato do endpoint do seu workspace e exemplos de requisição prontos para copiar. Experimente o exemplo com um dos seus canais.
4. Adicione um botão "Chat on WhatsApp" ao seu CRM, help desk ou tela de pedidos que chame a API e abra o url retornado.

observação

• O link abre o MonoChat para as pessoas que estão conectadas e têm permissão para ver essa conversa.
• A chamada apenas abre a conversa; ela não envia mensagem ao cliente. Use a WhatsApp Template API para escrever primeiro.

Recursos

Link da conversa

A resposta traz o link que abre a conversa no MonoChat e o id da conversa.

Cliente criado se necessário

Um cliente novo é criado com o nome e o sobrenome que você enviar; a resposta informa se o cliente já era conhecido.

Atribuição

Atribua a um atendente por id ou e-mail, ou a um grupo de trabalho.

Tela de documentação

A referência da API com o endereço exato de endpoint do seu workspace e exemplos de requisição prontos para copiar.

Referência da API

A chamada é um POST com um corpo JSON, autenticada com um token de API.

POST https://app.monochat.ai/api/<slug>/custom-functions/<app-folder>/methods/session-link.js
Authorization: Bearer <API_TOKEN>
Content-Type: application/json

• <slug> é o tenant slug do seu workspace, a parte depois de /tenants/ no seu endereço do MonoChat.
• <app-folder> é a pasta em que o app foi instalado. A tela Configurações › Session Link API mostra o endereço completo com os dois já preenchidos.
• Crie o token em Perfil › Tokens de API. Veja Tokens de API.

Campos da requisição

Campo	Obrigatório	Descrição
connectorBrand	sim	O tipo de canal, por exemplo whatsapp ou instagram.
channelUsername	sim	O nome de usuário do seu canal no MonoChat, por exemplo o seu número de WhatsApp sem +.
customer.identityType	sim	phoneNumber ou email.
customer.identity	sim	O telefone do cliente (código do país, sem +) ou o endereço de e-mail.
customer.firstname, customer.lastname	não	Usados quando o cliente é novo no MonoChat. Padrão -.
assignment.type	não	agent (id de usuário do atendente), agentIdentity (e-mail do atendente) ou workgroup (id do grupo de trabalho).
assignment.value	com assignment.type	O id ou e-mail para o qual atribuir a conversa.

Exemplo de requisição

curl --location 'https://app.monochat.ai/api/<slug>/custom-functions/<app-folder>/methods/session-link.js' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_TOKEN>' \
--data '{
  "connectorBrand": "whatsapp",
  "channelUsername": "905334445566",
  "customer": {
    "identityType": "phoneNumber",
    "identity": "905306667788",
    "firstname": "Ayşe",
    "lastname": "Yılmaz"
  },
  "assignment": { "type": "agentIdentity", "value": "sarah@yourcompany.com" }
}'

Resposta

{
  "result": {
    "url": "https://app.monochat.ai/tenants/<slug>?tab=messages&sessionTab=all&filter=…&_id=<sessionId>",
    "sessionId": "Zeii7vpeeFFnsJepZ",
    "isOldUser": true
  }
}

Campo	Descrição
url	Abre a conversa no MonoChat.
sessionId	O id da conversa. O mesmo cliente no mesmo canal sempre recebe a mesma conversa.
isOldUser	false quando o cliente foi criado por esta chamada.

Erros

Uma chamada com falha responde com um status de erro e uma mensagem:

Mensagem	Causa
connectorBrand, channelUsername and customer fields are required	Falta um campo obrigatório de nível superior.
customer.identityType must be one of: phoneNumber, email	identityType está ausente ou tem outro valor.
customer.identity field is required	Falta o telefone ou o e-mail do cliente.
Channel not found	Não há nenhum canal desse tipo com esse nome de usuário no seu workspace.
Customer Channel not found	Não foi possível associar o cliente a uma identidade de canal.
Agent user not found	Não há nenhum atendente com o e-mail informado em assignment.value.
401	O cabeçalho Authorization está ausente ou o token é inválido.

Capturas de tela

Um CRM, um help desk e uma tela de gestão de pedidos, cada um abrindo a conversa certa no MonoChatAtribuição da conversa a um atendente ou a um grupo de trabalho na mesma chamada de APIUm cliente e uma conversa novos criados automaticamente a partir da requisição de APIUma chamada de API retorna o link da conversaUm botão “Chat on WhatsApp” em um CRM abre a conversa do cliente com um cliqueChamar a API de novo para o mesmo cliente abre a conversa existente

Perguntas frequentes

O Session Link envia uma mensagem ao cliente?

Não. Ele apenas abre ou cria a conversa e retorna um link para ela. Para escrever primeiro ao cliente, use o app WhatsApp Template API.

Com quais canais funciona?

WhatsApp, Instagram e os outros canais conectados ao seu workspace do MonoChat. Você informa o tipo de canal e o nome de usuário do seu canal na requisição.

Vai criar conversas duplicadas?

Não. O mesmo cliente no mesmo canal sempre recebe a mesma conversa.

Quem pode abrir o link?

As pessoas que estão conectadas ao MonoChat e têm permissão para ver essa conversa.

Relacionados

• WhatsApp Template API
• Aplicativos da MonoStore
• Configurações do perfil
• Grupos de trabalho