Começar com a API, o Playground e os webhooks

Encontre a chave API, faça uma primeira chamada segura e ligue notificações sem expor credenciais.

Usar a referência API atual

Com sessão iniciada, abra a documentação API. A referência inclui endpoints suportados, campos obrigatórios e exemplos. Use-a para os detalhes dos pedidos; este guia explica o processo sem repetir a especificação.

Preparar a chave

Siga a verificação de identidade para ver ou copiar a chave. A documentação permite uma janela verificada de cinco minutos para consultar a chave e usar o Playground; gerar ou regenerar uma chave exige nova verificação. Trate-a como uma palavra-passe: guarde-a no servidor da aplicação, fora de repositórios públicos, código do navegador e capturas de ecrã.

Fazer um primeiro pedido seguro

1. Abra o Playground e selecione um exemplo apenas de leitura adequado à conta, como listar identidades SIP.
2. Reveja método, caminho e parâmetros. Use identificadores devolvidos para a sua conta, não valores de exemplo.
3. Escolha Run request e analise tanto o estado HTTP como o corpo da resposta.
4. Use o exemplo documentado na aplicação, com armazenamento seguro das credenciais.

O Playground utiliza a sua conta. Pedidos que enviam mensagens, fazem chamadas ou encomendam serviços podem executar ações reais e gerar custos. Não é um ambiente de testes gratuito.

Adicionar notificações webhook

Nas integrações da conta, adicione um endpoint HTTPS e escolha os eventos necessários. O segredo de assinatura do webhook é separado da chave API. Verifique assinaturas, processe cada evento uma só vez e confirme a receção rapidamente. Consulte os registos de entrega para diagnosticar problemas. Antes de repetir uma operação paga, leia as regras de repetição e pedidos duplicados; um timeout não prova, por si só, que falhou.

Guias relacionados

• Resolver problemas de entrega de webhooks
• Explicar a sua atividade em Communication reviews

Escolher a referência de serviço correta

A referência separa Lookup, Pricing, SIP, SMS, Contacts, Speech API, Phone Numbers, Voice API e Calls & recordings. Consulte cada endpoint para requisitos, campos e custos exatos. As chamadas no navegador têm um guia Webphone SDK próprio; não são o mesmo que o controlo de chamadas Voice API no servidor.

A permissão de um agente para ler a documentação não dá acesso à chave do titular nem à execução do Playground autenticada por chave. Peça ao titular para gerir as credenciais de integração em vez de partilhar a sua sessão.

Usar referências devolvidas e paginação

Trate as referências públicas como valores opacos: copie a referência CALL- completa da resposta, sem a construir nem usar um identificador telefónico interno. Chamadas históricas e ativas são listas distintas. Uma ação de controlo exige também um estado suportado; uma linha do histórico não é necessariamente controlável.

No histórico, siga pagination.next_cursor enquanto pagination.has_more for verdadeiro. Mantenha os filtros days, limit e identidade SIP originais. Não descodifique nem altere o cursor. Se expirar, reinicie a listagem e concilie pela referência pública. Um timestamp documentado como UTC precisa de conversão explícita para apresentação; não é automaticamente a hora local do navegador.

Tratar erros sem duplicar ações pagas

Leia o estado HTTP juntamente com o erro estruturado. Corrija erros de validação ou autorização antes de repetir. Respeite o intervalo documentado quando houver limitação de pedidos. Num timeout ou erro temporário de uma ação paga, verifique o estado e as regras de duplicação do endpoint antes de reenviar; mudar identificadores pode criar uma nova operação. Guarde a referência pública, a hora e o erro sem dados sensíveis para o suporte, nunca a chave API.