> ## Documentation Index
> Fetch the complete documentation index at: https://docs.notifique.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Usuário e agente

> USER é quem está no seu app. AGENT é a sua equipe falando pelo painel ou pela API.

<Tip>
  No Chat, **usuário** e **agente** não são papéis de permissão no seu produto. São **quem está falando na conversa**. Isso muda webhook, métricas e o JWT que você entrega no app.
</Tip>

## Em poucas palavras

|                       | Usuário (`USER`)                                         | Agente (`AGENT`)                                        |
| --------------------- | -------------------------------------------------------- | ------------------------------------------------------- |
| Quem é                | Pessoa autenticada **no seu app**                        | Membro do workspace (suporte, operação, bot da empresa) |
| Como cadastra         | `PUT /v1/chat/users` (padrão)                            | `POST /v1/chat/agents` (vincula `workspaceUserId`)      |
| JWT no app do cliente | Sim                                                      | Não. O app do cliente não deve receber JWT de agente    |
| Envio pelo painel     | Não                                                      | Sim — o painel fala como agente                         |
| Envio pela API Key    | Informe `senderExternalUserId` de um USER ou de um AGENT | Idem: o `senderExternalUserId` decide quem aparece      |
| Webhook               | `chat.received`                                          | `chat.sent`                                             |

## Quando usar USER

Use `USER` para **todo mundo que entra no chat pelo seu aplicativo** — cliente, motorista, lojista, aluno. Cada pessoa tem um `externalUserId` estável no **seu** banco.

Fluxo típico:

1. A pessoa faz login no seu app
2. Seu backend faz upsert (`PUT /v1/chat/users`) com o id dela
3. Seu backend emite o JWT (`POST /v1/chat/users/token`)
4. O app conecta o WebSocket com esse JWT e envia mensagens como ela

O JWT leva `kind: USER`. Quem tem esse token **é** essa pessoa na conversa.

## Quando usar AGENT

Use `AGENT` quando a mensagem deve aparecer como **a sua empresa**, não como um usuário final.

Situações:

* Alguém da equipe responde no **painel** (Chat ou Inbox) — a Notifique já cria o agente `agent:{idDoUsuárioDoWorkspace}`
* Seu backend envia um aviso na conversa **como suporte** (`senderExternalUserId` do agente)
* Você quer métricas de **enviadas** (agente) vs **recebidas** (usuário) separadas no detalhe do Chat App

```http theme={null}
POST /v1/chat/agents
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx
```

```json theme={null}
{
  "chatAppId": "clxxapp...",
  "workspaceUserId": "clxxuser...",
  "externalUserId": "agent:clxxuser...",
  "name": "Ana (suporte)"
}
```

`workspaceUserId` precisa ser membro do workspace. O `externalUserId` padrão é `agent:{workspaceUserId}`.

Depois, para falar como esse agente:

```json theme={null}
{
  "from": "clxxapp...",
  "to": ["cnv_xxxxx"],
  "type": "text",
  "payload": { "message": "Oi, como posso ajudar?" },
  "senderExternalUserId": "agent:clxxuser..."
}
```

## O que não misturar

* **Não** entregue JWT de `AGENT` no aplicativo do cliente. O cliente fala com o JWT de `USER`.
* **Não** cadastre a equipe como `USER` se ela atende pelo painel — o webhook iria como `chat.received` (como se fosse o cliente falando).
* Dois `USER` na mesma conversa 1:1 é conversa entre pessoas do seu produto. Um `USER` e um `AGENT` é atendimento.

## Flags do Chat App

Quem pode **criar conversa**, **criar grupo** e **adicionar membros** pelo JWT vale para qualquer pessoa com token de usuário. Agente pela API Key ignora essas flags: o backend sempre pode criar.

Ver [Quick Start](/chat-api/como-funciona/quick-start) e [Enviar mensagens](/chat-api/como-funciona/enviar-mensagens).