Pular para o conteúdo principal
O SDK tem dois clientes. A maioria das integrações cria os dois com a mesma chave. Os dois clientes aceitam uma chave da equipe ou uma credencial de projeto: Uma chave só alcança o que as permissões dela permitem. Cada página de tarefa lista as permissões que os métodos dela precisam. Veja Chaves de API para saber como criar chaves. Os exemplos destes guias usam três clientes chamados platform, project e messaging, criados como mostrado abaixo.

Crie um cliente de equipe

Um cliente de equipe alcança todos os projetos da equipe. Métodos que agem sobre um projeto recebem um argumento projectId.

Trabalhe dentro de um projeto

Chame project(projectId) para obter um cliente vinculado a um projeto:
Um cliente de projeto tem os recursos do nível de projeto: events, webhooks, webhookDeliveries, operations, flows, sipTrunks, calls, quickLinkSettings, sessionConfiguration, usage e callRetention. Recursos da equipe, como projects, members, billing, customers e campaigns, ficam no cliente de equipe. Com uma credencial de projeto, crie o cliente de projeto diretamente:
A API verifica se a credencial pertence a esse projeto.

Crie um cliente de mensagens

Use { type: "projectToken", value } para uma credencial de projeto. Os métodos de mensagens recebem o Número como primeiro argumento, por exemplo messaging.messages.send("<number-id>", ...).

Opções do cliente

Os dois clientes aceitam estas opções:

Defina a versão da API

apiVersion é a data do contrato da API, no formato YYYY-MM-DD. Ela é separada da versão do pacote. Fixe essa data para que uma nova versão da API não mude o formato das respostas sem você perceber. Leia Versionamento da API para ver as datas compatíveis. Você pode substituí-la em uma solicitação:

Defina opções por solicitação

Todo método recebe um último argumento opcional com opções por solicitação:

Leia uma resposta

Métodos que retornam um único resultado resolvem para { data, metadata }:
  • data é o corpo da resposta já interpretado. A maioria dos corpos envolve o resultado no próprio campo data, então você lê response.data.data. O tipo de retorno indica o formato de cada método.
  • metadata contém o status HTTP, o requestId, a apiVersion resolvida, o número de tentativas (attempts) e os headers da resposta.
Inclua o requestId quando entrar em contato com o suporte. Listas de eventos, webhooks, entregas, operações, registros de chamadas e opt-outs de chamadas retornam um objeto de página em vez disso. Veja Leia todas as páginas.

Entregue um token de cliente ao navegador

Código de navegador e de apps móveis não pode guardar uma chave da equipe nem uma credencial de projeto. Emita um token de cliente de curta duração no seu servidor e envie-o ao navegador:
O token só pode usar ações que estejam ao mesmo tempo no teto fixado na emissão e nas regras de cliente atuais do Número. Passe allow para definir um teto explícito; sem ele, o token registra as ações configuradas na sessão naquele momento. Leia e altere as regras com clientTokens.retrieveRules e clientTokens.updateRules. A emissão precisa de todas estas permissões: sessions:manage, messages:write, contacts:read, presence:read, presence:observe e mcp. Veja Tokens de cliente.

Chame um endpoint sem método do SDK

raw.request envia uma solicitação autenticada para qualquer caminho da API. Ele usa a credencial, a versão da API, o timeout e as configurações de novas tentativas do cliente:
Um cliente de projeto restringe raw.request ao próprio projeto.

Controles de gastos

Use o transporte autenticado do cliente de equipe para ler limites ou mudar uma ordem. Leituras exigem billing:read; escritas exigem billing:manage e Pay-As-You-Go. Credenciais de projeto e de cliente não podem fazer essas solicitações.
Envie a lista completa, do mais alto para o mais baixo. Para ordenar Clientes ou números, use scope: "customer" ou scope: "number", inclua projectId e passe todos os Clientes ativos ou números reais desse projeto. Uma alteração simultânea retorna um conflito; leia de novo antes de escolher uma nova ordem. Os limites mensais usam a própria revisão por recurso. limitCredits: null remove um limite; zero bloqueia novas cobranças. O serviço pago mantém seu período pago. Para painéis nativos de Clientes e números, use a leitura de um recurso e o salvamento combinado com platform.raw.request. Eles aceitam scope: project, customer ou number no caminho. Um salvamento combinado exige limitCredits, priority, expectedBudgetRevision e expectedPriorityRevision; um conflito mantém os dois valores inalterados. A prioridade do projeto tem precedência. Os números herdam a prioridade do Cliente; uma prioridade de número mais alta a substitui dentro do projeto. Os números atribuídos a um Cliente compartilham o limite mensal dele. As leituras dos diretórios de limites e prioridades aceitam scope=project para omitir os diretórios de Clientes e números. A criação inicial de um QuickLink real também aceita billingControls: { limitCredits: 250, priority: 30 } com uma credencial billing:manage da equipe. Os controles são aplicados antes da admissão do pareamento. Conexões de teste e suplementares rejeitam esses campos. Use a solicitação raw documentada até que uma versão do pacote inclua métodos tipados.

Verifique o status da API

SystemClient não precisa de credencial. Use-o em health checks:
Ele também tem status(), health() e ping().

Recursos de cada cliente

Client (equipe): MessagingClient: A referência da API documenta todos os endpoints por trás desses métodos.

Ranking misto de financiamento

Leia as prioridades de um projeto com GET /platform/billing/priorities?projectId=PROJECT_UUID. Reordene os Clientes e os números reais desse projeto juntos com PUT /platform/billing/priorities:
Inclua todos os Clientes ativos e números reais do projeto selecionado. Use a revisão da leitura correspondente; alterações simultâneas retornam 409. Uma prioridade de número mais alta fica acima da prioridade do Cliente dentro do projeto. A prioridade do projeto e todos os limites de gastos continuam valendo. Use o método de solicitação raw do cliente publicado para essas chamadas. Chaves da organização e tokens de projeto são gerenciados por uma pessoa conectada ao Console. O SDK não tem recursos de gerenciamento de chaves. As operações de tokens de cliente continuam disponíveis.