Tokens de Acesso por Papel
O endpoint POST /api/calls/{id}/access emite um token de acesso opcional que identifica o papel de um participante na chamada: customer (cliente), attendant (atendente) ou supervisor. O token é anexado ao link da chamada e permite que sua integração distinga os participantes por papel.
O token é opcional — o link funciona sem ele
O link da chamada (https://{sua-organizacao}.videochamada.com.br/chamada/{callId}) funciona sem token: qualquer pessoa com o link entra normalmente. O token de acesso não controla a entrada na chamada — ele serve para vincular papel e permissões ao participante que entra por aquele link. Use-o quando sua integração precisar diferenciar cliente, atendente e supervisor.
Requisição
Cabeçalhos:
Parâmetros:
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id |
string (path) | Sim | ID da chamada |
role |
string (body) | Sim | Papel do participante: customer, attendant ou supervisor. Qualquer outro valor — ou campos extras no corpo — retorna 400 |
O corpo deve conter exatamente o campo role:
Exemplos
curl -X POST "https://api.videochamada.com.br/api/calls/{id}/access" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "Content-Type: application/json" \
-d '{"role": "attendant"}'
import requests
response = requests.post(
"https://api.videochamada.com.br/api/calls/{id}/access",
headers={"Authorization": "Bearer {API_TOKEN}"},
json={"role": "attendant"},
)
access_token = response.json()["accessToken"]
call_url = (
"https://{sua-organizacao}.videochamada.com.br/chamada/{callId}"
f"#access_token={access_token}"
)
print(call_url)
const response = await fetch(
'https://api.videochamada.com.br/api/calls/{id}/access',
{
method: 'POST',
headers: {
Authorization: 'Bearer {API_TOKEN}',
'Content-Type': 'application/json',
},
body: JSON.stringify({ role: 'attendant' }),
},
);
const { accessToken } = await response.json();
const callUrl =
`https://{sua-organizacao}.videochamada.com.br/chamada/{callId}` +
`#access_token=${encodeURIComponent(accessToken)}`;
Resposta
| Campo | Tipo | Descrição |
|---|---|---|
accessToken |
string | Token assinado que vincula o papel ao participante naquela chamada |
Como usar o token
Anexe o token ao link da chamada como fragmento (#), no parâmetro access_token:
Envie a cada participante o link com o token do papel correspondente — por exemplo, o link com token customer para o cliente e o link com token attendant para o atendente.
Validade: o token expira junto com a chamada (campo expiresAt da chamada). Se a chamada não tiver expiração definida, o token vale por 24 horas a partir da emissão.
Erros
| Status | Mensagem | Quando |
|---|---|---|
| 400 | Expected exactly one participant role |
Corpo ausente, com campos extras ou sem o campo role |
| 400 | Invalid participant role |
role diferente de customer, attendant ou supervisor |
| 404 | Call not found |
A chamada não existe |
| 403 | Call does not belong to this project |
A chamada pertence a outro projeto (API key incorreta) |
| 410 | Call access has expired |
A chamada já expirou (expiresAt no passado) |
Boas práticas
- Um token por participante: emita um token para cada pessoa, com o papel correto — não reutilize o mesmo link com token entre papéis diferentes.
- Gere na hora do envio: emita o token no momento de enviar o convite (por e-mail, WhatsApp ou dentro do seu sistema), já que ele expira com a chamada.
- Fragmento, não query string: o token vai após
#(fragmento da URL), portanto não é enviado ao servidor em requisições HTTP nem aparece em logs de acesso intermediários. - Não é controle de entrada: se você precisa impedir que alguém sem o link entre na chamada, controle a distribuição do próprio link — o token define papel, não autorização de entrada.