API

Peça a ligação. Receba o desfecho.

Q: Como funciona a autenticação?

Chave por empresa, no cabeçalho Authorization: Bearer, com escopos. Uma chave de uma empresa não alcança dados de outra empresa da mesma conta, e isso é conferido no servidor, não na aplicação que chama.

Pedir ligações e mensagens, consultar atendimentos e contatos, com chave e escopos por empresa. Webhooks assinados de volta, e um servidor MCP para o seu próprio agente operar a plataforma.

Bearerchave com escopos

HMACassinatura de saída

MCPservidor incluso

Eventos saindo para o seu sistemaatendimento 254f1b8d

mensagem.recebidachega no WhatsApp, no site ou no e-mailaguardando

ligacao.encerradao áudio e a transcrição sobemaguardando

atendimento.resumidodesfecho, o que foi combinado e os dadosaguardando

HMAC-SHA2563 tentativas, backoff 2 s / 4 s

Primeiros passos

Começar em três chamadas

Autenticar, pedir uma ligação, receber o resultado. O resto é detalhe do seu fluxo.

curl -X POST https://api.voicespeak.app/v1/ligacoes \
  -H "Authorization: Bearer sk_empresa_..." \
  -H "Content-Type: application/json" \
  -d '{
    "agente": "isabella",
    "telefone": "+5511999990000",
    "linha": "voip",
    "missao": "cobranca-amigavel",
    "contexto": {
      "fatura": "2026-08",
      "valor_brl": 240.00
    }
  }'

curl -X POST https://api.voicespeak.app/v1/mensagens \
  -H "Authorization: Bearer sk_empresa_..." \
  -H "Content-Type: application/json" \
  -d '{
    "agente": "isabella",
    "canal": "whatsapp",
    "para": "+5511999990000",
    "modelo": "retorno_combinado",
    "variaveis": { "hora": "14h" }
  }'

curl https://api.voicespeak.app/v1/atendimentos/254f1b8d \
  -H "Authorization: Bearer sk_empresa_..."

{
  "atendimento": "254f1b8d",
  "canal": "telefone",
  "desfecho": "retorno_combinado",
  "combinado": "Ligar amanha as 14h",
  "transcricao": "https://.../transcricao.txt",
  "gravacao": "https://.../audio.mp3",
  "custo_brl": 0.84
}

Chave por empresa

Com escopos. Uma chave não alcança dados de outra empresa da conta.

Tentativas por webhook

Com espera crescente, e o evento continua legível pela API depois.

Servidor MCP incluso

Para o agente de IA do próprio cliente operar a plataforma.

SDK obrigatório

É HTTP com JSON. Use o cliente que o seu stack já tem.

Referência curta

Os endereços que importam

A referência completa é servida pela própria plataforma, junto do seu ambiente.

Endereço	O que faz	Escopo
POST `/v1/ligacoes`	Pede uma ligação, com missão e contexto	`ligacoes:escrever`
POST `/v1/mensagens`	Envia mensagem por WhatsApp, site ou e-mail	`mensagens:escrever`
GET `/v1/atendimentos`	Lista atendimentos, com filtro por canal e desfecho	`atendimentos:ler`
GET `/v1/atendimentos/{id}`	Traz o dossiê: resumo, combinado e dados coletados	`atendimentos:ler`
GET `/v1/contatos`	Consulta contatos e o histórico por pessoa	`contatos:ler`
POST `/v1/campanhas`	Cria campanha a partir de uma lista de contatos	`campanhas:escrever`
POST `/v1/webhooks`	Cadastra o endereço que recebe os eventos	`webhooks:escrever`
GET `/v1/uso`	Consumo do período e limites do plano	`uso:ler`

Respostas

Erros, e o que fazer com cada um

O código diz o que aconteceu. O corpo diz o que fazer.

Código	Erro	O que fazer
401	`CHAVE_INVALIDA`	A chave não existe ou foi revogada. Gere outra no painel
403	`ESCOPO_AUSENTE`	A chave é válida mas não tem o escopo daquele endereço
403	`FORA_DA_JANELA`	WhatsApp oficial fora das 24 h. Use um modelo aprovado
409	`NAO_PERTURBE`	O contato está na lista de quem não quer ser chamado
409	`FORA_DO_HORARIO`	A janela de discagem da empresa está fechada agora
422	`PRECO_NAO_APROVADO`	O item do catálogo ainda não foi aprovado por uma pessoa
429	`LIMITE_SIMULTANEAS`	O plano chegou ao teto de ligações ao mesmo tempo

Os erros com nome de trava (NAO_PERTURBE, PRECO_NAO_APROVADO) são o mesmo controle que vale no painel. Ver Travas e auditoria.

Servidor MCP

O seu agente operando a plataforma

Para quem já tem um assistente interno e não quer escrever um cliente HTTP para ele.

{
  "mcpServers": {
    "voicespeak": {
      "url": "https://api.voicespeak.app/mcp",
      "headers": {
        "Authorization": "Bearer sk_empresa_..."
      }
    }
  }
}

As ferramentas expostas seguem os mesmos escopos da chave: o agente do cliente não alcança nada que a chave não alcance.

Perguntas frequentes

Como funciona a autenticação?

Chave por empresa, no cabeçalho Authorization: Bearer, com escopos. Uma chave de uma empresa não alcança dados de outra empresa da mesma conta, e isso é conferido no servidor, não na aplicação que chama.

A documentação fica onde?

É servida pela própria plataforma, junto do seu ambiente, então o que você lê corresponde à versão que está respondendo as suas chamadas.

O que é o servidor MCP?

Um servidor que expõe a plataforma como ferramenta para agentes de IA do próprio cliente. Se você já tem um assistente interno, ele consegue consultar atendimentos e pedir ligações sem você escrever um cliente HTTP.

Dá para pedir uma ligação com contexto?

É o caso de uso principal. O pedido leva o contexto da conversa anterior, e o agente liga já sabendo do que se trata, em vez de começar perguntando o que o cliente já respondeu.

Como trato um webhook que falhou?

Há três tentativas com espera crescente. O evento também pode ser lido depois pela API, então uma queda do seu endereço não perde informação.

Existe limite de chamadas?

Sim, por plano, junto com o limite de ligações ao mesmo tempo. O consumo fica visível em GET /v1/uso.

Continua em

RecursoIntegraçõesCRM, ERP, webhooks assinados, servidor MCP e compatibilidade com a Evolution.RecursoTodos os canaisO mesmo agente no WhatsApp, no telefone, no site e no e-mail, com um histórico só.RecursoPainel do gestorConversas de todos os canais, desfecho medido, custo em reais e o relatório do dia.RecursoTravas e auditoriaCada empresa isolada, credenciais no cofre e o registro de toda decisão do agente.

Teste a API com o seu ambiente

Na demonstração a gente gera uma chave de teste, aponta um webhook para o seu endereço e faz a primeira ligação pela API, com você olhando.

Precisa de escopos específicos ou contrato? Fale com o time.