# Chaves de API (SyBox)

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.

### Como ativar o gateway e gerar chaves

1. Vá até Definições > Integrações > Chaves de API.
2. Ative o seletor "Gateway de API".
3. Clique em "Nova chave".
   ![Settings, API keys: keys that let another program send through SyBox, and the "New key" button](https://www.sybox.io/res/sybox/help/pt/turn-on-the-gateway-and-create-a-key-3.webp?v=4fa40036)
4. 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.
5. Defina o "Nome do dispositivo ou programa" (ex.: "Computador Recepção" ou "ERP Financeiro"). É recomendável criar uma chave para cada aplicação.
6. 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)".
7. 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.
8. Clique em Salvar.
9. 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".

### Como alterar, desativar ou apagar chaves

1. 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.
   ![To change, pause or delete a key: "Edit" marked on the screen in SyBox](https://www.sybox.io/res/sybox/help/pt/change-pause-or-delete-a-key-1.webp?v=b177b910)
2. Use o botão Ativar / Desativar para pausar a integração temporariamente.
3. Clique em Excluir e confirme: "Excluir esta chave de API? Qualquer programa que ainda a use para de funcionar imediatamente."

**Q: 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.

**Q: 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.

**Q: 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.

**Q: 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.

**Q: 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.

**Q: 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".

Source: https://www.sybox.io/pt/help/api-keys