Envio de mensagens
Campanhas API
Fluxo Geral de Utilização
Antes de começar a enviar mensagens, é necessário seguir algumas etapas essenciais:
Criação de uma Campanha
Para gerenciar e organizar os envios de mensagens, o primeiro passo é criar uma campanha. As campanhas servem como o núcleo do envio, onde você pode definir as configurações e o propósito das suas mensagens.
Autenticação e Geração de Token Temporário
Após a criação da campanha, você deve realizar a autenticação na API. Esse processo retornará um token temporário, que será usado para autenticar as requisições de envio de mensagens e outras operações.
Envio de Mensagens
Com o token temporário em mãos, você poderá utilizar as rotas específicas para realizar o envio de mensagens. O token garante a segurança e validade da operação, sendo necessário renová-lo periodicamente.
Observação
O uso correto das rotas da API depende de um entendimento claro dessas etapas. Abaixo, você encontrará detalhes técnicos e exemplos práticos para cada endpoint da API, ajudando você a implementar a integração com facilidade.
Autenticação
A autenticação na API Chatlabs é o ponto de entrada para acessar os serviços de envio de mensagem da plataforma. Para autenticar, é necessário utilizar as credenciais de um usuário do tipo Administrador já cadastrado na plataforma.
Rota de Autenticação
Endpoint:
POST <dns_api>/api/login
Exemplo de Requisição
POST <dns_api>/api/login
Content-Type: application/json
Header: company-slug
{
"email": "[email protected]",
"password": "password"
}Parâmetros
email (string): O e-mail do usuário Administrador registrado no Chatlabs.
password (string): A senha associada a esse usuário.
company-slug (header): Slug da companhia no Chatlabs
Resposta de Sucesso
Se as credenciais forem válidas, a API retornará um token temporário no seguinte formato:
{
"expiresIn": "2024-12-30T14:55:17.013Z",
"token": "lgye954wip15fcxvei42s33tojhtqi2vrr2eo3unpqkfl0c8"
}Detalhes da Resposta:
token (string): Token de acesso temporário que deve ser incluído no cabeçalho das requisições subsequentes.
expiresIn (string): Data exata que o token vai expirar. (Timezone 0)
Observação
Certifique-se de armazenar o token com segurança, pois ele será necessário para realizar qualquer requisição autenticada na API. Caso o token expire, será necessário realizar o login novamente para obter um novo token.
Criação de Campanha
A criação de uma campanha é o primeiro passo para começar a enviar mensagens através da API Chatlabs. Essa etapa organiza os envios de mensagens e conecta os recursos necessários, como telefone, templates e arquivos.
Como Criar uma Campanha
Acesse a Página de Campanhas API
No painel de controle da plataforma, clique na aba Campanhas para visualizar as opções de gerenciamento de campanhas.
Na tela de criação de campanha, escolha o número do WhatsApp que será utilizado para o envio das mensagens.
Escolha o Template da Meta
Selecione o template da meta associado ao número de WhatsApp escolhido.
Adicione um Arquivo (Apenas se o template possui arquivo)
Se o template possuir imagem ou documento este campo é obrigatório.
Salvar a Campanha
Após preencher os campos necessários, clique em Salvar para criar a campanha. A nova campanha aparecerá na lista de campanhas disponíveis para uso.
Obtenha a URL pública da Campanha
Após salvar, a tela de Campanhas exibirá o URL da campanha recém-criada. Essa url será essencial para realizar o envio de mensagens via API.
Localize a url na coluna correspondente na lista de campanhas.
Envio de Mensagens
Após criar uma campanha e obter a URL da campanha, é possível enviar mensagens para os clientes utilizando a API.
Rota para Envio de Mensagens
Endpoint:
POST <dns_api>/api/campaign/send-message/<id_público_do_template>
Substitua <id_público_do_template> pelo ID do template utilizado para a campanha.
Exemplo de Requisição
POST <dns_api>/api/campaign/send-message/<id_público_do_template>
Content-Type: application/json
x-api-token: <seu_token_temporário>
{
"clientPhone": "+5553981054127",
"clientName": "John Doe"
}
Parâmetros obrigatórios
clientName (string): Nome do contato.
clientPhone (string): O número de telefone do cliente, incluindo o código do país, no formato internacional (exemplo: "+55" para o Brasil).
x-api-token (header): Token de autenticação temporário obtido na etapa de login. Observação: implementada feature para uso do endpoint com client-credentials.
Parâmetros extras
chatStartedClosed (boolean): Opção que se true vai ignorar se o cliente possui um chat em aberto no sistema.
metaTemplateVariables (object): Objeto contendo o nome e valor das variáveis do template.
file (upload): Se você deseja enviar outro arquivo (por exemplo, boleto), e não o arquivo padrão do template, apenas faça o upload por meio deste campo em Multipart/Form-Data.
POST <dns_api>/api/campaign/send-message/<id_público_do_template>
Content-Type: application/json
x-api-token: <seu_token_temporário>
{
"clientPhone": "+5553981054127",
"clientName": "John Doe",
"metaTemplateVariables": {
"Nome Variável 1": "<valor>",
"Nome Variável 2": "<valor>"
},
"chatStartedClosed": true,
"file": <arquivo>
}Respostas
Sucesso
A solicitação de envio foi validada com sucesso:
{
"success": true
}Cliente com Chat em Aberto
Se o cliente já possui um chat em andamento, a API retornará:
{
"statusCode": 400,
"message": "CLIENT_ALREADY_HAS_CHAT_OPEN",
"timestamp": "2024-12-30T14:54:51.783Z"
}Token Inválido
Se o token enviado no cabeçalho for inválido ou inexistente, a API retornará:
{
"statusCode": 403,
"message": "API_TOKEN_INVALID_OR_INEXISTENT",
"timestamp": "2024-12-30T14:54:19.466Z"
}Observações
Certifique-se de que o ID público do template seja o correto para a campanha.
O número de telefone do cliente deve estar formatado corretamente, incluindo o código do país.
Verifique a validade do token antes de fazer a requisição para evitar falhas.
Caso o cliente já tenha um chat em aberto, nenhuma mensagem será enviada.
O arquivo enviado na mensagem é sempre o que está ligado a campanha criada dentro da plataforma.
Last updated