Chaves de API
Atualizado em
Onde: Definições > Integrações > Chaves de API
Para que serve:
"Dê a um programa externo sua própria chave para enviar pelo SyBox — o token do WhatsApp nunca sai do servidor, e uma chave que vazou pode ser revogada individualmente." Seus softwares de gestão, frente de caixa ou ERP conectam-se usando essa chave, sem precisar expor os acessos reais do WhatsApp.
Recursos disponíveis via chave de API (detalhados na Documentação para Desenvolvedores):
- Disparar mensagens de WhatsApp pelo número oficial conectado. O formato de envio segue a WhatsApp Cloud API da Meta, permitindo reaproveitar integrações existentes mudando apenas a URL e a chave. Suporta texto, modelos, imagens, arquivos e botões interativos, retornando os erros e confirmações originais da Meta.
- Registar uma reclamação ou abrir chamados a partir de sistemas externos, vinculando o evento a um cliente existente no SyBox.
- Importar SMS de um telefone para centralizar os atendimentos na caixa de entrada.
- Iniciar suas automações a partir de outro sistema (uma chave do tipo "Iniciar uma automação").
- Localizar, ler e alterar seus contatos a partir de outro sistema (uma chave do tipo "Ler e atualizar contatos").
Quem tem acesso: o administrador principal e atendentes com a permissão "Gerenciar canais".
O controle "Gateway de API":
No topo da página de Chaves de API há o botão seletor "Gateway de API", desativado por padrão. Enquanto estiver desligado, todas as chaves ficam inoperantes e a criação de novos acessos é bloqueada com o aviso: "O gateway de API está desativado. Ative-o na chave no topo desta tela antes de criar chaves." A alteração salva no mesmo instante do clique.
- Vá até Definições > Integrações > Chaves de API.
- Ative o seletor "Gateway de API".
- Clique em "Nova chave".
- Selecione o "Tipo de chave":
- "Enviar pelo WhatsApp": envia mensagens para a sua base de contatos.
- "Registar uma reclamação": cadastra ocorrências no SyBox, sem permissão de envio.
- "Importar SMS de um telefone": encaminha as mensagens recebidas no aparelho para a caixa de entrada.
- "Iniciar uma automação": o programa inicia as automações cujo "Começa quando" é "Outro programa chama o SyBox" (POST /v1/automation com o "phone" do cliente e, opcionalmente, "event" e "data"). Não permite enviar mensagens. Veja Definições > IA e automação > Automações.
- "Ler e atualizar contatos": o programa localiza contatos, lê um contato e altera seu nome, e-mail, campos de contato e etiquetas (POST /v1/contacts/search, /get, /update e /labels). Não permite enviar mensagens. A chave atua em nome da pessoa que a criou: ela vê apenas os contatos que essa pessoa pode ver, só funciona se essa pessoa puder abrir a lista de contatos e ver números, e só pode alterar contatos se essa pessoa puder editá-los. Se essa pessoa for desativada, a chave para de funcionar.
- Defina o "Nome do dispositivo ou programa" (ex.: "Computador Recepção" ou "ERP Financeiro"). É recomendável criar uma chave para cada aplicação.
- Para chaves do tipo "Enviar pelo WhatsApp", configure:
- "Envia de": escolha a linha de WhatsApp responsável pelos disparos (obrigatório).
- "Permitir mensagens de texto livre": sim ou não.
- "Permitir modelos aprovados": sim ou não. Ao menos uma dessas opções deve estar ativa para evitar o aviso: "Permita pelo menos mensagens de texto livre ou modelos — caso contrário, a chave não poderá enviar nada."
- "Permitir envio de mídia": autoriza fotos, áudios e arquivos.
- "Modelos" (opcional): limite aos modelos autorizados, separando os nomes por vírgula (deixe vazio para liberar todos).
- "Países de destinatários permitidos" (opcional): informe os códigos DDI de dois dígitos (ex.: BR,PT,US). Deixe em branco para envio global.
- "Envio permitido das" ... "Para": defina a faixa de horário permitida. Para liberar 24 horas, selecione horários idênticos. O fuso considerado é o do espaço de trabalho.
- "Limite diário de mensagens (0 = ilimitado)".
- Para a opção "Importar SMS de um telefone", marque "Apenas contatos e clientes" para descartar mensagens de desconhecidos direto no celular. Desmarque essa opção apenas se o telefone for de uso exclusivamente corporativo.
- Clique em Salvar.
- A tela exibirá a "URL base" e a "Chave de API". "Copie esta chave agora — ela é exibida apenas uma vez." Cole esses dados na tela de conexão do seu software.
Dados exibidos no cartão da chave:
- Identificação da chave e número de saída configurado (ou etiqueta do tipo de integração).
- Os últimos dígitos da credencial para identificação visual rápida.
- O campo "usado pela última vez", com data e hora ou "nunca".
- Regras de restrição ativas: "Somente texto livre", "Somente modelos", "sem mídia", "Modelos", países liberados, grade de horário e a volumetria no formato: enviados hoje / limite diário. Integrações de SMS com filtro aberto mostram "Todos os números".
- Clique em Editar no cartão desejado para modificar nomes, restrições e número. O tipo de chave e o código secreto completo não podem ser alterados depois de criados.
- Use o botão Ativar / Desativar para pausar a integração temporariamente.
- Clique em Excluir e confirme: "Excluir esta chave de API? Qualquer programa que ainda a use para de funcionar imediatamente."
Perdi minha chave de API. Como faço para visualizar o código de novo?
Por segurança, ela nunca é mostrada novamente. Exclua a chave antiga e gere uma nova para atualizar o seu sistema.
Suspeito que uma chave foi vazada. O que fazer?
Exclua ou desative a chave imediatamente. Apenas ela perderá a conexão, sem afetar o número do WhatsApp nem as demais integrações.
A lista "Envia de" não mostra nenhuma opção.
Essa opção só lista linhas ativas e conectadas no momento. Ative um número primeiro em Definições > Mensagens > Canais.
As tentativas de envio do meu sistema são recusadas.
Confirme se a opção "Gateway de API" está ativada e se a chave está com status ativo. Verifique as travas de horário, países permitidos, uso de mídia ou modelos e o limite diário. Lembre-se também das regras da Meta: mensagens livres só podem ser entregues dentro da janela de 24 horas do cliente.
Uma chave para "Registar uma reclamação" pode responder clientes?
Não, esse comportamento é bloqueado por padrão. Chaves de registro de chamados não enviam mensagens, e chaves de envio não abrem chamados. Separe as funções criando chaves distintas.
Ainda possuo uma chave legada do tipo "Receber de um programa". Ela continua funcionando?
Sim, integrações antigas desse tipo seguem operando normalmente. Contudo, não é mais possível gerar novas chaves com esse formato. Para novos cadastros com essa finalidade, use a opção "Registar uma reclamação".