API do ChatSIA.

O que dá para fazer.

• Criar e atualizar contatos a partir do seu sistema, com nome, telefone, e-mail e os campos que você criar.
• Responder numa conversa ou mandar mensagem só com o telefone do cliente, na hora ou programada para o dia e o horário que você escolher. A mensagem fica na conversa, junto com o resto do atendimento. No WhatsApp oficial, a Meta cobra cada mensagem no cartão da sua conta do WhatsApp Business, e fora da janela de 24 horas só sai modelo aprovado. No Instagram e no Messenger, só dentro da janela que a Meta permite depois da última mensagem do cliente.
• Receber um aviso no seu sistema quando chega conversa, mensagem ou contato novo, ou quando uma conversa é resolvida.
• Etiquetar a conversa, passar para uma pessoa ou um time e marcar como resolvida.
• Criar cartões no funil, mudar a etapa e marcar como ganho ou perdido. No Profissional e no Avançado.
• Levar para o seu sistema o volume de conversas e o tempo da primeira resposta e de resolução, por pessoa, canal, time e etiqueta, com token de uma pessoa administradora.

Em quais planos.

• Em todos os planos, também nos 7 dias grátis: a API da conta, os webhooks, as telas do seu sistema dentro do ChatSIA e o canal próprio.
• No Profissional e no Avançado: o funil pela API, com cartões, etapas, ganho e perdido.
• Só no Avançado: as ferramentas próprias do agente de IA, que consultam o seu sistema durante a conversa.

Preços e o que entra em cada plano estão em Planos.

Exemplos prontos para copiar.

Os exemplos usam dados fictícios. Antes, guarde o token e o endereço da conta no terminal:

CHATSIA_TOKEN="cole-aqui-o-seu-token"
API="https://app.servicosia.com.br/api/v1/accounts/123"   # troque 123 pelo número da sua conta

Conferir o token.

curl "https://app.servicosia.com.br/api/v1/profile" \
  -H "api_access_token: $CHATSIA_TOKEN"

A resposta traz o seu nome e as contas que você acessa, com o número e o seu papel em cada uma. Se algum proxy do seu lado descartar cabeçalho com sublinhado, mande o mesmo token em Api-Access-Token.

Listar as conversas abertas.

curl "$API/conversations?status=open&page=1" \
  -H "api_access_token: $CHATSIA_TOKEN"

As conversas vêm em data.payload, a de atividade mais recente primeiro, em páginas: peça page=2, page=3 e assim por diante, até a lista vir vazia. O status aceita open, pending, resolved, snoozed ou all; sem ele, vêm só as abertas. Para ver um canal só, acrescente &inbox_id=7 ao endereço. O id de cada conversa é o mesmo número que aparece no painel. Com token de agente, vêm só as conversas das caixas de entrada em que essa pessoa está.

Mandar uma mensagem numa conversa.

curl -X POST "$API/conversations/1042/messages" \
  -H "api_access_token: $CHATSIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content": "Oi, Mariana! Sua avaliação está confirmada para sexta, às 15h."}'

A mensagem sai pelo canal da conversa 1042 e fica registrada como enviada pela pessoa dona do token. Com "private": true, ela vira nota interna, que o cliente não vê. Se a conversa estava resolvida, volta a ficar aberta. No WhatsApp oficial, fora da janela de 24 horas, mande um modelo aprovado pela Meta em template_params, com o nome e o idioma exatos do modelo: {"content": "Oi, Mariana! Sua avaliação está confirmada.", "template_params": {"name": "confirmacao_avaliacao", "language": "pt_BR", "processed_params": {"body": {"1": "Mariana"}}}}. Texto livre fica com status de falha. Na resposta, message_type vem em número (0 é recebida, 1 é enviada); nos avisos, vem em texto (incoming, outgoing).

Criar um contato.

curl -X POST "$API/contacts" \
  -H "api_access_token: $CHATSIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Mariana Costa", "phone_number": "+5548999999999",
       "email": "mariana@example.com", "identifier": "cliente-1042"}'

O telefone vai no formato internacional, com + e o código do país. O identifier é o código do cliente no seu sistema: não se repete na conta e serve para achar o contato depois, pela busca. Telefone, e-mail ou código que já estejam na conta voltam com erro 422, então busque antes com GET /contacts/search?q=. A exceção é o mesmo celular escrito com ou sem o nono dígito: nesse caso, o ChatSIA aproveita o contato que já existe. O id do contato criado vem em payload.contact.id; é ele que vai em contact_id nas outras chamadas.

Webhooks: avisos para o seu sistema.

Em Configurações, Integrações, Webhooks, clique em Adicionar novo Webhook. Informe o endereço do seu sistema e um nome, escolha as caixas de entrada (sem escolher, valem todas) e marque os eventos. Ao criar, o ChatSIA mostra o segredo do webhook. Guarde-o para conferir a assinatura; ele também aparece depois, ao editar o webhook.

A cada evento, o ChatSIA manda um POST em JSON para o seu endereço, com o nome do evento no campo event.

Trecho de um aviso de mensagem recebida, com dados fictícios:

{
  "event": "message_created",
  "id": 98765,
  "content": "Oi! Tem horário na sexta?",
  "message_type": "incoming",
  "private": false,
  "sender": { "id": 4567, "name": "Mariana Costa", "phone_number": "+5548999999999", "identifier": "cliente-1042" },
  "conversation": { "id": 1042, "inbox_id": 7, "status": "open", "labels": [] },
  "inbox": { "id": 7, "name": "WhatsApp" },
  "account": { "id": 123, "name": "Clínica Exemplo" }
}

Assinatura.

Cada aviso traz três cabeçalhos com o prefixo da plataforma, terminados em -Timestamp, -Signature e -Delivery:

• o que termina em -Timestamp traz a hora do envio, em segundos;
• o que termina em -Signature traz sha256= seguido do HMAC SHA-256, feito com o segredo do webhook, do texto {hora}.{corpo}: a hora do cabeçalho anterior, um ponto e o corpo exato que chegou;
• o que termina em -Delivery identifica a entrega. Use para ignorar um aviso repetido.

Se chegar também um cabeçalho terminado em -Global-Signature, ignore: ele usa outro segredo, que não é o da sua conta.

Conferência em Node.js:

import crypto from 'node:crypto';

// cabecalhos: os cabeçalhos do pedido
// corpo: o texto exato que chegou, antes de virar JSON
export function avisoConfere(cabecalhos, corpo, segredo) {
  const achar = (fim) => {
    const nome = Object.keys(cabecalhos).find((n) => {
      const m = n.toLowerCase();
      return m.endsWith(fim) && !m.includes('global');
    });
    return nome ? String(cabecalhos[nome]) : '';
  };
  const hora = achar('-timestamp');
  const recebida = achar('-signature');
  const esperada = 'sha256=' + crypto
    .createHmac('sha256', segredo)
    .update(`${hora}.${corpo}`)
    .digest('hex');
  const recente = Math.abs(Date.now() / 1000 - Number(hora)) < 300; // até 5 minutos de diferença
  const a = Buffer.from(recebida);
  const b = Buffer.from(esperada);
  return recente && a.length === b.length && crypto.timingSafeEqual(a, b);
}

No Express, leia o corpo cru com express.raw({ type: 'application/json' }) e só depois converta para JSON.

Entrega.

• Responda com 200 em menos de 5 segundos, que é o tempo que o ChatSIA espera hoje, e deixe o trabalho pesado para depois. Se o seu endereço demorar, responder com erro ou estiver fora do ar, aquele aviso se perde: não há nova tentativa. Por isso, de tempos em tempos, consulte a API para pegar o que ficou para trás.
• Os avisos saem por uma fila e podem chegar fora de ordem. Para saber como uma conversa está agora, consulte a API.
• O ChatSIA precisa alcançar o seu endereço pela internet. Use https.
• Para avisar só em certas condições, use a ação Enviar evento de Webhook nas regras de automação ou nas macros. Ela manda os dados da conversa para o endereço que você indicar, sem assinatura.

Limites e boas práticas.

• O token faz tudo o que a pessoa dona dele pode fazer no ChatSIA. Para integrar, crie uma pessoa só para isso, com papel de agente, nas caixas de entrada que a integração usa. Ela ocupa uma das 20 vagas de atendente do plano.
• Use token de administrador só quando precisar. Relatórios e webhooks pela API pedem esse token, e ele também lê os segredos dos canais e dos webhooks.
• Guarde o token no servidor, nunca no navegador nem no app. Se ele vazar, clique em Reiniciar, na mesma tela onde você copiou, e confirme: o token antigo para de funcionar na hora.
• Pagine as listas e prefira os avisos a perguntar à API a cada poucos segundos. Se a plataforma frear as suas chamadas, a resposta é 429: espere um pouco e tente de novo.
• Chamar a API não gasta créditos de IA. Se a sua integração cria mensagens de cliente numa caixa com o agente de IA ligado, o agente responde, e cada resposta gasta créditos.

Respostas de erro.