# Criar Conversa

> Cria uma nova conversa externa vinculada obrigatoriamente a um lead existente e atribui ao setor de atendimento desejado.

`POST https://crm.wavups.com/api/v1/account-external-conversation`

Página: https://crm.wavups.com/docs/api/conversas/criar

**Atenção:**
  **Padrão Estrito de Telefone (DDI + DDD + Número)**
  
  Os números de telefone devem ser enviados exclusivamente no formato de dígitos com **DDI + DDD/Código de Área + Número** (exemplo Brasil: `5547999999999`, exemplo EUA: `14155552671`), sem espaços, traços, parênteses ou o símbolo `+`.
  
  **Qualquer divergência neste formato causará falhas nos disparos da API do WhatsApp e duplicação de leads no sistema.**

**Nota:**
  **Fluxo de Criação em Duas Etapas:**
  Para direcionar um lead a um setor específico antes do primeiro contato:
  1. Primeiro registre o lead através do endpoint [Criar Lead](https://crm.wavups.com/docs/api/leads/criar) para obter o `id` do lead.
  2. Em seguida, utilize este endpoint enviando o `leadId` e o `accountChatSectorId` desejado (ex: Setor de Vendas).

## Requisição

`POST https://crm.wavups.com/api/v1/account-external-conversation`

- `Token` (string, obrigatório, header):
  Seu token de autenticação.

### Body

- `leadId` (string, obrigatório, body):
  ID do Lead retornado na criação do lead (`POST /lead`). **Campo obrigatório.**

- `accountChatSectorId` (string, body):
  ID do setor do chat para atribuir a conversa (ex: Setor de Vendas, Suporte).

- `contactPhone` (string, body):
  Telefone do contato no formato estrito internacional (`5547999999999`). Caso não informado, o telefone cadastrado no Lead será utilizado.

- `contactName` (string, body):
  Nome do contato da conversa. Caso não informado, o nome cadastrado no Lead será utilizado.

- `contactUsername` (string, body):
  Username ou identificador social do contato (ex: username do Instagram).

- `accountIntegrationId` (string, body):
  ID da integração da conta (consulte [Listar Integrações](https://crm.wavups.com/docs/api/integracoes/listar)). Opcional caso o setor já possua integração associada.

- `conversationOwnerId` (string, body):
  ID do membro da conta responsável pela conversa. Caso não informado, utilizará o `leadOwner` do lead.

- `status` (string, body):
  Status da conversa (padrão: `active`).

- `state` (string, body):
  Estado inicial do atendimento da conversa (padrão: `NEW`). Valores aceitos: `NEW`, `AI_ANSWERING`, `NEEDS_HUMAN`, `NO_RESPONSE`, `COMPLETED`, `ARCHIVED`.

---

## Resposta

Retorna o objeto da conversa criada (status HTTP 201).

- `id` (string):
  Identificador único da conversa.

- `contactName` (string):
  Nome do contato.

- `contactPhone` (string | null):
  Telefone do contato formatado.

- `leadId` (string):
  ID do lead associado.

- `accountChatSectorId` (string | null):
  ID do setor associado.

- `status` (string):
  Status da conversa.

- `state` (string):
  Estado atual do atendimento da conversa. Padrão: `NEW`. Valores possíveis: `NEW`, `AI_ANSWERING`, `NEEDS_HUMAN`, `NO_RESPONSE`, `COMPLETED`, `ARCHIVED`.

- `createdAt` (string):
  Data e hora de criação (ISO 8601).

---

## Exemplos

### Exemplo de requisição

```bash Criar Conversa
curl --request POST \
  --url 'https://crm.wavups.com/api/v1/account-external-conversation' \
  --header 'Token: SEU_TOKEN_DE_API' \
  --header 'Content-Type: application/json' \
  --data '{
  "leadId": "clead12345",
  "accountChatSectorId": "csector001",
  "contactPhone": "5511988887777",
  "contactName": "Carlos Eduardo"
  }'
```

### Exemplo de resposta

```json 201
{
  "id": "clconv123",
  "contactName": "Carlos Eduardo",
  "contactPhone": "5511988887777",
  "contactUsername": null,
  "leadId": "clead12345",
  "accountChatSectorId": "csector001",
  "status": "active",
  "state": "NEW",
  "unreadCount": 0,
  "createdAt": "2026-02-20T10:00:00.000Z",
  "AccountChatSector": {
  "id": "csector001",
  "name": "Vendas",
  "color": "#10B981"
  },
  "PlatformIntegration": {
  "id": "cplat001",
  "name": "WhatsApp"
  }
}
```