Docs
Páginas desta seção

Filtros de leads e conversas

Por recurso

  • Autenticação
  • Usuário
  • Workspaces
  • Departamentos
  • Chaves de API
  • Especificação da API
  • Eventos
  • Webhooks
  • Auditoria
  • Conversas
  • Mensagens agendadas
  • Notas internas
  • Atalhos de mensagem
  • Dados da conversa
  • Etiquetas
  • Funis
  • Etapas
  • CRM
  • Visões salvas
  • Leads
  • Memórias do lead
  • Campos personalizados
  • Carteira de clientes
  • Negociações
  • Negociações automáticas
  • Chamados
  • Chat da equipe
  • WhatsApp: cadastro
  • WhatsApp: contas
  • WhatsApp: números
  • WhatsApp: modelos
  • WhatsApp: formulários
  • WhatsApp: campanhas
  • WhatsApp: iniciar conversa
  • WhatsApp não oficial: instâncias
  • WhatsApp não oficial: campanhas
  • WhatsApp não oficial: grupos
  • Instagram
  • Facebook
  • TikTok
  • Telegram
  • Mercado Livre
  • WebChat
  • RCS e SMS
  • E-mail: domínios e caixas
  • E-mail: campanhas
  • E-mail: API transacional
  • Público de campanhas
  • Rascunhos de campanha
  • Troncos SIP
  • Filas de atendimento
  • Listas de ligação
  • Campanhas de ligação
  • Histórico de chamadas
  • Gravações de chamadas
  • Cobrança de chamadas
  • Agentes
  • Fluxos
  • Segredos do workspace
  • Automações
  • Elo
  • Mídia gerada com IA
  • Estúdio
  • Métricas de atendimento
  • Pesquisas de satisfação
  • SLA
  • Relatórios
  • Análises
  • Anúncios
  • Páginas
  • Páginas: rotas públicas
  • Central de ajuda
  • Links curtos
  • Mídias
  • Google
  • Google Planilhas
  • Lojas e infoprodutos
  • Sincronização com CRM
  • Agenda
  • Saldo
  • Faturas
  • Add-ons
  • Preços
  • Afiliados
  • Notificações
  • Tutoriais
  • CEP
  • WebSockets
  • Webhooks recebidos

Referência

Comece por aqui

Crie uma integração só de leitura para explorar a API, envie a chave e teste as rotas /v1 no navegador.

Esta referência lista todas as rotas da API da Vozkoia, agrupadas por recurso, com os parâmetros, os corpos, as respostas e os códigos de erro de cada uma. Para entender os conceitos antes, leia os guias.

O jeito mais seguro de explorar é com uma integração só de leitura: uma conta de sistema que só consegue ler, criada por você para testar as rotas /v1 sem risco de mudar nada.

URL base

text
https://api.vozkoia.com

Todas as rotas desta referência partem desse endereço, com HTTPS. As conexões WebSocket usam wss://api.vozkoia.com. Não há ambiente de testes; veja URL base e ambientes.

1. Escolha um workspace de testes

As chamadas agem sobre dados reais, como qualquer outra: não existe uma cópia de testes da API. Se puder, crie um workspace só para explorar, com alguns leads e conversas de exemplo, e faça os passos abaixo nele.

2. Crie uma integração só de leitura

Uma integração é uma conta de sistema do workspace. Ela não faz login, não aparece entre os membros e age só com as permissões e os departamentos que você escolher. Quem cria precisa poder gerenciar as chaves de API do workspace.

  1. No aplicativo, abra Menu lateral › Integrações e clique em Nova integração.
  2. Dê um nome que diga o propósito, por exemplo Exploração da API.
  3. Em Permissões, marque só ações de leitura (read) dos recursos que quer explorar, como leads:read, conversations:read e opportunities:read. Não marque nenhuma ação de criar, editar, enviar ou apagar.
  4. Em Departamentos da integração, escolha os departamentos cujos dados ela pode ver.
  5. Crie a integração.

Membros, cargos, chaves de API, planos e recursos pessoais nunca são dados a uma integração, então nem aparecem na lista.

3. Crie uma chave

Na integração, clique em Chaves, depois em Nova chave. Escolha uma validade curta, como 30 dias, e copie a chave: ela começa com wsk_ e aparece uma única vez. Guarde-a como uma senha.

4. Envie a chave

Envie a chave no cabeçalho Authorization, com o esquema Bearer e um espaço:

http
Authorization: Bearer wsk_SUA_CHAVE

A chave já traz o workspace, então X-Workspace-ID não é preciso; um workspace diferente do da chave responde 403 com o código workspace_mismatch. Para restringir a um dos departamentos da integração, envie X-Department-ID.

bash
curl "https://api.vozkoia.com/v1/leads?page=1&pageSize=20" \
  -H "Authorization: Bearer wsk_SUA_CHAVE"

5. Teste no navegador

Cada rota /v1 desta referência tem um painel para enviar a chamada de verdade:

  1. Abra a rota que quer testar.
  2. No campo de autenticação WorkspaceKey, preencha a palavra Bearer, um espaço e a chave: Bearer wsk_....
  3. Preencha os parâmetros da rota e envie.

Com uma integração só de leitura, uma rota que cria, edita, envia ou apaga responde 403 com um código como create_permission_required. Essa é a resposta esperada: ela mostra a permissão que faltaria, sem mudar nada no workspace.

O que a chave não abre

  • Rotas fora de /v1: respondem 401 com o código api_key_not_accepted. Elas servem o painel e mudam sem aviso. As únicas exceções são as três rotas antigas da API de e-mail transacional.
  • Gestão de integrações e chaves (/v1/integrations e as chaves de cada integração): declaram só BearerAuth e aceitam apenas o token de login de uma pessoa, obtido com POST /auth/login. Veja Autenticação.

Especificação e SDKs

A especificação OpenAPI das rotas /v1, a mesma que gera os SDKs, sai em GET /v1/openapi.json, com a mesma chave. Use-a para gerar um cliente na sua linguagem ou importar a API numa ferramenta de testes.

Quando terminar

Revogue a chave em Integrações › Chaves, ou desative a integração, que revoga todas as chaves dela na hora. Para integrar um sistema de verdade, crie outra integração só com as permissões de que ele precisa e uma chave por sistema.

Próximas páginas