Tokens de usuario vs bot e usar tokens em requisicoes HTTP

Entenda a diferenca entre um token de usuario e um de servico (bot) e aprenda a enviar sua chave de API em requisicoes HTTP para a API do Omnifox.

Jun 26, 2026

Veja este passo no vídeo · Criar uma chave de API

Ao criar uma chave de API voce pode marca-la como Token de servico (bot). Essa escolha muda como as mensagens e eventos gerados com a chave se comportam. Este artigo mostra a diferenca e como enviar o token nas suas requisicoes HTTP.

Token de usuario vs token de servico (bot)

Token de usuario (caixa Token de servico desmarcada): as acoes sao atribuidas a voce como agente humano. Use para automatizar o seu proprio trabalho.

Token de servico (bot) (caixa marcada): pensado para integracoes (n8n, Zapier, scripts). Com um token bot:

  • As mensagens enviadas nao sao atribuidas automaticamente ao usuario dono da chave.
  • Nao afetam o status online do usuario.
  • Nao disparam notificacoes push para o dispositivo do usuario.

Regra pratica: se uma maquina usa a chave, marque como bot. Se voce a usa para agilizar seu trabalho manual, deixe como token de usuario.

Usar o token em requisicoes HTTP

A API REST do Omnifox fica em /api/v1/. Autentique cada requisicao com o cabecalho Authorization: Bearer:

Authorization: Bearer 123_aBc...seuTokenCompleto
Accept: application/json

Exemplo com cURL para listar contatos:

curl https://omnifox.io/api/v1/contacts \
  -H "Authorization: Bearer 123_aBc...seuTokenCompleto" \
  -H "Accept: application/json"

Workspace

A chave ja esta vinculada a um workspace (o que voce escolheu ao cria-la). Essa e a fonte da verdade: se enviar workspace_id na requisicao, ele deve coincidir com o da chave, ou a API rejeita. Nao e preciso envia-lo quando a chave ja tem um definido.

Escopos

Cada endpoint exige o escopo correspondente. Se a chave nao tiver, por exemplo, write:messages, os envios falham com erro de permissao. Reveja escopos e permissoes.

Como verificar

Uma resposta 200 OK com dados confirma que o token e os escopos estao corretos.

Se nao funcionar

  • 401 Unauthorized: token ausente, copiado errado ou expirado. Verifique o cabecalho Authorization e se a chave nao venceu.
  • 403 / erro de escopo: falta a permissao do endpoint na chave. Edite a chave e adicione o escopo.
  • Erro de workspace: o workspace_id enviado nao coincide com o da chave. Remova o parametro ou use a chave do workspace correto.
  • Minhas mensagens ficam atribuidas a mim sem querer: voce usou um token de usuario; recrie a chave como bot.

Dica

Guarde o token em uma variavel de ambiente (OMNIFOX_TOKEN) e nunca o envie para um repositorio.

Artigos relacionados

Isso foi útil?

Artigos relacionados

Fale conosco no WhatsApp