Como ativar o gateway e gerar chaves

Atualizado em

No SyBox, isso é feito em Definições > Integrações > Chaves de API.

  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
  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.

Perguntas

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".

Mais sobre Chaves de API.