Autenticação e permissões
Toda requisição leva uma chave de API no cabeçalho Authorization:
Authorization: Bearer ck_<sua chave>A chave é criada em Configurações › Integrações › Chaves de API e tem o formato ck_<prefixo>_<segredo>. O conecta/ai guarda só um resumo dela, por isso ela é mostrada uma única vez. Perdeu? Revogue e crie outra.
A organização vem da chave
A chave pertence a uma organização, e a API só enxerga essa organização. Nenhum parâmetro escolhe outra. Um identificador de outra organização responde 404, como se não existisse.
Permissões
Cada endpoint exige uma permissão, marcada na chave quando ela é criada. Sem ela, a resposta é 403 com code: "insufficient_scope", e a frase diz qual permissão faltou. A permissão de cada endpoint está na referência.
| Permissão | Na tela de chaves | O que libera |
|---|---|---|
conversas:read | Leitura de conversas | Lê as conversas e as mensagens de todos os canais pela API, inclusive o texto que o cliente escreveu. Notas internas e conversas de teste não saem. Use para levar o atendimento ao seu BI ou CRM. |
contatos:read | Leitura de contatos | Lê os contatos e os telefones e canais de cada um pela API. São dados pessoais dos seus clientes: guarde a chave só no servidor. |
configuracao:read | Leitura da configuração | Lê a configuração da organização pela API, como a lista de etiquetas. Não altera nada. |
agentes:edit | Configuração do agente | Lê e altera a configuração do agente de IA pela API v1. Dá poder de mudar como o agente fala com o cliente. Conceda com parcimônia. |
Conceda só o que a integração usa. Uma chave para o BI precisa apenas de leitura.
O que a API nunca devolve
- Conversa de contato de teste: é ensaio da equipe, não atendimento.
- Nota interna da equipe.
- Texto de mensagem apagada (vem
deleted: trueetext: null). - Link para arquivo de mídia: a mensagem descreve o anexo (tipo, formato e nome).
- Etiqueta pessoal de atendente.
Guarde a chave no servidor
A chave dá acesso aos dados que as permissões dela liberam, inclusive telefone e mensagens dos seus clientes. Use-a só no servidor. Nunca a coloque em página web, aplicativo instalado no celular do cliente ou repositório de código.
A chave revogada ou vencida para de funcionar na hora e responde 401 com code: "invalid_credential". Sem o cabeçalho, a resposta é 401 com code: "unauthenticated".