Criar token de chat · Diligens Docs

Esta rota troca a API key por um token de chat para um usuário final. O seu backend a chama a partir de uma rota própria, acessível apenas ao usuário autenticado, e devolve o token ao navegador. O SDK do chat usa esse token para conversar com a Diligens, e a API key nunca sai do servidor. O código completo da rota do seu backend está em Crie a rota de token.

Requisição

curl -X POST "https://api.diligensai.com.br/api/v1/chat/token" \
  -H "X-API-Key: $DILIGENS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "external_id": "loja-123" }'

const response = await fetch('https://api.diligensai.com.br/api/v1/chat/token', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.DILIGENS_API_KEY, 'Content-Type': 'application/json' },
  // O external_id vem da SUA sessão, nunca do navegador.
  body: JSON.stringify({ external_id: String(user.id) }),
});
const { token, expires_at } = await response.json();

import os
import requests

response = requests.post(
    "https://api.diligensai.com.br/api/v1/chat/token",
    headers={"X-API-Key": os.environ["DILIGENS_API_KEY"]},
    # O external_id vem da SUA sessão, nunca do navegador.
    json={"external_id": str(user.id)},
    timeout=10,
)
data = response.json()

<?php
$ch = curl_init('https://api.diligensai.com.br/api/v1/chat/token');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: ' . getenv('DILIGENS_API_KEY'),
        'Content-Type: application/json',
    ],
    // O external_id vem da SUA sessão, nunca do navegador.
    CURLOPT_POSTFIELDS => json_encode(['external_id' => (string) $user->id]),
]);
$data = json_decode(curl_exec($ch), true);

Resposta

{
  "token": "Q2F7...",
  "external_id": "loja-123",
  "expires_at": "2026-09-26T15:05:00Z"
}

Obtenha o external_id da sua sessão

Nunca use um valor enviado pelo navegador. Se o external_id vier de um parâmetro da requisição, um usuário poderá abrir o chat e acessar os dados de outro. Consulte Usuário final.

Corpo da requisição

external_id string Obrigatório

O identificador, no seu sistema, do usuário que vai conversar, com até 255 caracteres. Se ele ainda não existir na Diligens, será criado.

Resposta

A API responde com o status 201 e o token em token, válido até expires_at.

Regras

O token é válido por 5 minutos e pode ser usado quantas vezes for necessário até expirar. Cada chamada gera um novo token, e os anteriores continuam válidos até expirarem.
O token dá acesso somente ao chat daquele external_id. Ele não serve para o PUT /orders nem para as outras rotas desta referência.
Não é necessário guardar o token no seu backend. O SDK o mantém em memória e solicita um novo antes que ele expire.
A rota funciona mesmo sem créditos (consulte Créditos) e conta no limite de chamadas da API key.

Erros

Status	`code`	Quando
400	`COMMON_002`	`external_id` ausente, vazio ou com mais de 255 caracteres
401	`APIKEY_002`	API key ausente, inválida ou regenerada
402	`APIKEY_003`	A conta ainda não tem nenhuma recarga de créditos paga
403	`EXTUSER_002`	O `external_id` é novo e a conta já chegou ao limite de `external_id`s
429	`COMMON_005`	Limite de chamadas da API key excedido

Os detalhes do formato de erro estão em Erros.