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
projectId.
Trabalhe dentro de um projeto
Chameproject(projectId) para obter um cliente vinculado a um 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:
Crie um cliente de mensagens
{ 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 campodata, então você lêresponse.data.data. O tipo de retorno indica o formato de cada método.metadatacontém ostatusHTTP, orequestId, aapiVersionresolvida, o número de tentativas (attempts) e osheadersda resposta.
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: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:
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 exigembilling:read; escritas exigem billing:manage e
Pay-As-You-Go. Credenciais de projeto e de cliente não podem fazer essas
solicitações.
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:
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 comGET /platform/billing/priorities?projectId=PROJECT_UUID.
Reordene os Clientes e os números reais desse projeto juntos com PUT /platform/billing/priorities: