# Ligar

POST /calls

Liga (voz) para um contato. Sem `url` nem `base64`, o telefone só toca: se atenderem, a ligação fica muda até desligarem ou acabar `max_seconds`. Com o áudio em `url` ou `base64` (MP3, WAV ou OGG, até 25 MB), a api toca o arquivo quando atenderem e desliga quando ele acaba.

A resposta volta assim que a ligação é oferecida, sem confirmação do WhatsApp: acompanhe pelo evento `call.updated`. Ligação de vídeo não é suportada.


## Autenticação

```json
[
  {
    "token": []
  }
]
```

```json
{
  "token": {
    "name": "token",
    "type": "apiKey",
    "in": "header"
  }
}
```

## Corpo da requisição

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "to"
        ],
        "properties": {
          "to": {
            "type": "string",
            "description": "Número com DDI (só dígitos) ou id."
          },
          "max_seconds": {
            "type": "integer",
            "minimum": 0,
            "description": "Desliga depois deste tempo; `0` ou ausente, sem limite."
          },
          "url": {
            "type": "string",
            "description": "Link do áudio para tocar quando atenderem (a api baixa antes de ligar). Mande `url` ou `base64`, não os dois."
          },
          "base64": {
            "type": "string",
            "description": "O áudio em base64 (aceita `data:`)."
          },
          "audio": {
            "type": "object",
            "additionalProperties": false,
            "description": "Obsoleto: mande `url` ou `base64` soltos, como na mídia do `POST /messages`. Ainda aceito, sem os soltos junto.",
            "properties": {
              "url": {
                "type": "string",
                "description": "Link do arquivo (a api baixa antes de ligar)."
              },
              "base64": {
                "type": "string",
                "description": "O arquivo em base64 (aceita `data:`)."
              }
            },
            "deprecated": true,
            "minProperties": 1,
            "not": {
              "required": [
                "url",
                "base64"
              ]
            }
          }
        },
        "not": {
          "description": "`url` ou `base64`, um dos dois; e sem os soltos junto do `audio` obsoleto.",
          "anyOf": [
            {
              "required": [
                "url",
                "base64"
              ]
            },
            {
              "required": [
                "audio",
                "url"
              ]
            },
            {
              "required": [
                "audio",
                "base64"
              ]
            }
          ]
        }
      },
      "example": {
        "to": "5511999999999",
        "url": "https://exemplo.com/aviso.mp3"
      }
    }
  }
}
```

## Respostas

```json
{
  "201": {
    "description": "Ligação oferecida, ainda sem resposta do contato.",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "call"
          ],
          "properties": {
            "call": {
              "$ref": "#/components/schemas/OrkesioCall"
            },
            "audio": {
              "type": "object",
              "additionalProperties": false,
              "description": "Só com `audio`: o que vai tocar.",
              "properties": {
                "queued": {
                  "type": "boolean",
                  "description": "O áudio toca quando atenderem."
                }
              }
            }
          }
        },
        "example": {
          "call": {
            "id": "ABEiGmo8oqkAcAKrBYQAAAAA_1",
            "chat": {
              "id": "5511999999999@s.whatsapp.net",
              "type": "direct"
            },
            "direction": "out",
            "video": false,
            "status": "offered",
            "at": "2026-10-17T12:00:00.000Z",
            "sent_by_api": true
          },
          "audio": {
            "queued": true
          }
        }
      }
    }
  },
  "400": {
    "description": "Número inválido, ou áudio inválido (formato ou tamanho).",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/OrkesioError"
        },
        "example": {
          "error": "invalid_request",
          "message": "Número sem WhatsApp."
        }
      }
    }
  },
  "401": {
    "description": "Token inválido ou ausente.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/OrkesioError"
        },
        "example": {
          "error": "unauthorized",
          "message": "Token inválido."
        }
      }
    }
  },
  "429": {
    "$ref": "#/components/responses/RateLimited"
  },
  "500": {
    "$ref": "#/components/responses/InternalError"
  },
  "501": {
    "$ref": "#/components/responses/CloudUnsupported"
  },
  "503": {
    "$ref": "#/components/responses/Disconnected"
  }
}
```

**Estado:** Disponível

## Compatibilidade de canais

| Canal | Compatível | Observação |
|---|---|---|
| WhatsApp (Web) | Sim |  |
| WhatsApp (API oficial) | Não | Ligação pela API oficial ainda não. |
| Instagram | Não |  |
| Messenger | Não |  |
| Telegram | Não |  |

## Eventos que esta rota gera

O que chega no seu webhook (ou em `GET /events`) depois desta rota.

### [`call.updated`](/webhook/call.updated): `offered`, `accepted`, `ended`...

```json
{
  "id": "evt_01JAB3K9ZQ7V0M4T8R2X6WYD5H",
  "type": "call.updated",
  "created_at": "2026-10-17T12:00:00.000Z",
  "inbox": {
    "id": "r0269625d29bfbd",
    "name": "loja",
    "phone": "5511888888888",
    "channel": "whatsapp_web"
  },
  "data": {
    "id": "B1C2D3E4",
    "chat": {
      "id": "5511999999999@s.whatsapp.net",
      "lid": "123456789012345@lid",
      "type": "direct"
    },
    "author": {
      "id": "5511888888888@s.whatsapp.net"
    },
    "direction": "out",
    "video": false,
    "status": "offered",
    "at": "2026-10-17T12:00:00.000Z",
    "sent_by_api": true
  }
}
```

### [`call.log`](/webhook/call.log): o registro no fim

```json
{
  "id": "evt_01JAB3K9ZQ7V0M4T8R2X6WYD5H",
  "type": "call.log",
  "created_at": "2026-10-17T12:00:00.000Z",
  "inbox": {
    "id": "r0269625d29bfbd",
    "name": "loja",
    "phone": "5511888888888",
    "channel": "whatsapp_web"
  },
  "data": {
    "message": {
      "id": "3EB0A1B2C3D4E5F60718",
      "chat_id": "5511999999999@s.whatsapp.net",
      "author": {
        "id": "5511999999999@s.whatsapp.net",
        "phone": "5511999999999",
        "lid": "123456789012345@lid",
        "name": "Maria"
      },
      "direction": "out",
      "sent_at": "2026-10-17T12:00:00.000Z",
      "category": "call",
      "type": "call",
      "video": false,
      "result": "missed",
      "device": "android"
    },
    "chat": {
      "id": "5511999999999@s.whatsapp.net",
      "lid": "123456789012345@lid",
      "type": "direct",
      "name": "Maria Souza"
    }
  }
}
```

## Antes e depois (uazapi → Orkesio)

Na uazapi: `POST /call/make`.

- `number` → `to`; `call_duration` → `max_seconds`; `fileUrl` → `url` ou `base64`.
- Resposta: a ligação no formato do evento (`call`); `audio` só diz se ficou na fila.

## #/components/schemas/OrkesioCall

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Id da ligação."
    },
    "chat": {
      "$ref": "#/components/schemas/OrkesioChat"
    },
    "author": {
      "$ref": "#/components/schemas/OrkesioParticipant"
    },
    "direction": {
      "type": "string",
      "enum": [
        "in",
        "out"
      ],
      "description": "`in` (recebida) ou `out` (feita pela inbox)."
    },
    "sent_by_api": {
      "type": "boolean",
      "description": "A ligação foi feita por `POST /calls` (não pelo celular). Dá para ignorar as próprias ligações no webhook."
    },
    "video": {
      "type": "boolean",
      "description": "`true` em chamada de vídeo; `false` em chamada de voz. Só vem em `offered`: nos outros estados o campo não sai."
    },
    "status": {
      "type": "string",
      "enum": [
        "offered",
        "accepted",
        "rejected",
        "ended",
        "missed"
      ],
      "description": "`offered` (tocando), `accepted` (atendida), `rejected` (recusada), `ended` (encerrada) ou `missed` (não atendida)."
    },
    "duration_seconds": {
      "type": "integer",
      "description": "Duração em segundos, quando encerrada."
    },
    "at": {
      "type": "string",
      "format": "date-time",
      "description": "Quando mudou. ISO 8601 em UTC com milissegundos."
    }
  },
  "required": [
    "id",
    "chat",
    "direction",
    "status",
    "at",
    "sent_by_api"
  ],
  "additionalProperties": false,
  "description": "Ligação."
}
```

## #/components/schemas/OrkesioChat

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Id da conversa: o id nativo do canal com o sufixo dele. WhatsApp: `<número>@s.whatsapp.net`, `<id>@g.us` (grupo), `<id>@newsletter`, `status@broadcast` ou, na API oficial, `<BSUID>@bsuid` para contato sem telefone. Nos outros canais: `<psid>@messenger`, `<igsid>@instagram`, `<id>@telegram` (conversa com o bot) e `<id>@telegram-business` (conversa da sua conta, pelo Telegram Business); o post comentado é `<id da mídia>@instagram_post` ou `<id do post>@facebook_post` (no Facebook o id do post tem `_`, como `110198307512345_987654321`). Guarde como veio, sem montar a partir de outro campo."
    },
    "lid": {
      "type": "string",
      "description": "**Só WhatsApp.** LID da conversa, quando conhecido (só no `whatsapp_web`).",
      "x-only": "whatsapp"
    },
    "type": {
      "type": "string",
      "enum": [
        "direct",
        "group",
        "broadcast",
        "newsletter",
        "channel",
        "status",
        "post"
      ],
      "description": "Tipo da conversa. `newsletter` é newsletter do WhatsApp (o que o app chama de Canal); `channel` fica para os canais de transmissão do Telegram, que ainda não chegam. `post` é um post do Instagram ou da Página do Facebook: os comentários são as mensagens."
    },
    "name": {
      "type": "string",
      "description": "Nome para exibir: em conversa direta, o `contact_name` (agenda do celular) ou, sem ele, o `push_name` (perfil do contato); em grupo ou canal, o nome do grupo ou do canal. Não é um nome a mais: é um dos outros, já escolhido. No post, o começo da legenda."
    },
    "contact_name": {
      "type": "string",
      "description": "**Só WhatsApp.** Só em conversa direta: o nome salvo na agenda do celular; ausente quando o número não está salvo.",
      "x-only": "whatsapp"
    },
    "push_name": {
      "type": "string",
      "description": "**Só WhatsApp.** Só em conversa direta: o nome que o contato usa no perfil do WhatsApp, quando conhecido.",
      "x-only": "whatsapp"
    },
    "username": {
      "type": "string",
      "description": "Só em conversa direta: o nome de usuário do contato (o @, sem o `@`), quando ele tem e o canal informa. No WhatsApp, vem no `GET /chats/{chat_id}`; no Instagram e no Telegram, em toda conversa, depois que a pessoa escreve."
    },
    "unread_count": {
      "type": "integer",
      "description": "Quantas mensagens não lidas a conversa tem."
    },
    "awaiting_reply": {
      "type": "boolean",
      "description": "O contato espera resposta: a última mensagem é dele e ninguém concluiu a conversa."
    },
    "assigned_to": {
      "type": "string",
      "description": "Quem atende esta conversa: o id do atendente. Ausente = sem responsável. É da conversa, não do lead: o mesmo contato pode ter outro responsável em outra inbox."
    },
    "ticket_open": {
      "type": "boolean",
      "description": "Atendimento aberto nesta conversa."
    },
    "reply_window_until": {
      "type": "string",
      "format": "date-time",
      "description": "Até quando dá para mandar mensagem livre: 24 horas depois da última mensagem do contato (reação e edição não contam). Depois disso, só template (API oficial) ou mensagem com tag (Messenger, Instagram). Vem nos canais oficiais (API oficial do WhatsApp, Instagram, Messenger, Telegram Business), na lista, no detalhe, no `chat.updated`, em `message.received` e em `message.sent`; ausente no WhatsApp Web e na conversa com o bot do Telegram, que não têm janela, e quando a janela já fechou."
    },
    "archived": {
      "type": "boolean",
      "description": "Arquivada."
    },
    "pinned": {
      "type": "boolean",
      "description": "Fixada."
    },
    "muted_until": {
      "type": "string",
      "format": "date-time",
      "description": "Silenciada até; ausente quando não está silenciada. ISO 8601 em UTC com milissegundos."
    },
    "labels": {
      "type": "array",
      "items": {
        "type": "string",
        "description": "Id da etiqueta (o `id` de `GET /labels/list`, como em `PATCH /chats` (`labels`))."
      },
      "description": "**Só WhatsApp.** Etiquetas do WhatsApp Business (ids), como no celular. As tags do CRM são outras, em `lead.tags`.",
      "x-only": "whatsapp"
    },
    "last_message_at": {
      "type": "string",
      "format": "date-time",
      "description": "Última mensagem. ISO 8601 em UTC com milissegundos."
    },
    "picture_url": {
      "type": "string",
      "description": "Foto completa da conversa (do contato ou do grupo), quando conhecida."
    },
    "picture_preview_url": {
      "type": "string",
      "description": "Miniatura da foto, quando conhecida (use nas listas)."
    },
    "blocked": {
      "type": "boolean",
      "description": "Contato bloqueado."
    },
    "follows_business": {
      "type": "boolean",
      "description": "**Só Instagram.** O contato segue a conta da empresa. Vem quando a api já leu o perfil do contato: na mensagem recebida (uma vez por dia) ou no `GET /chats/{chat_id}`, que lê na hora se faltar. A lista e os eventos mostram só o que já foi lido; sem o campo, a Meta ainda não disse.",
      "x-only": "instagram"
    },
    "verified": {
      "type": "boolean",
      "description": "**Só Instagram.** O contato tem selo de verificado. Vem como `follows_business`.",
      "x-only": "instagram"
    },
    "ephemeral_seconds": {
      "type": "integer",
      "description": "**Só WhatsApp.** Mensagens temporárias: duração em segundos (`0` = desligado).",
      "x-only": "whatsapp"
    },
    "last_message_preview": {
      "type": "string",
      "description": "Texto ou legenda da última mensagem, para listas."
    },
    "last_message_type": {
      "type": "string",
      "enum": [
        "text",
        "image",
        "video",
        "audio",
        "voice",
        "document",
        "sticker",
        "location",
        "contacts",
        "poll",
        "poll_vote",
        "buttons",
        "list",
        "carousel",
        "location_request",
        "flow",
        "interactive_reply",
        "order",
        "product",
        "payment",
        "group_invite",
        "newsletter_invite",
        "event_response",
        "sticker_pack",
        "video_note",
        "live_location",
        "scheduled_call",
        "album",
        "share",
        "story_mention",
        "event",
        "reaction",
        "call",
        "group_participant",
        "system",
        "unavailable",
        "template",
        "unknown"
      ],
      "description": "Tipo da última mensagem (os mesmos de `type` da mensagem), para o ícone da lista. A conversa guarda só o nome do tipo, sem o conteúdo: áudio e mensagem de voz vêm os dois como `audio`, e as mensagens interativas como `buttons`, `list` ou `template` (carrossel, flow, cobrança e pedido de localização vêm como `buttons`). A ligação também é prévia (`call`) e sobe a conversa, como no WhatsApp, sem somar não lida. A entrada e saída de membro do grupo não é prévia. Ausente quando não se sabe."
    },
    "last_message_direction": {
      "type": "string",
      "enum": [
        "in",
        "out"
      ],
      "description": "Quem mandou a última mensagem, como em `direction` da mensagem: `in`, o contato (no grupo, um participante); `out`, a inbox (o \"Você:\" da lista). Ausente quando não se sabe."
    },
    "last_message_author": {
      "$ref": "#/components/schemas/OrkesioParticipant",
      "description": "Quem mandou a última mensagem (`id`, `phone` quando é um número). `name` vem no grupo (o nome que o participante mostra, quando conhecido) e na conversa direta quando foi o contato. Ausente quando não se sabe. Para a prévia \"Ana: oi\" da lista."
    },
    "group": {
      "type": "object",
      "description": "**Só WhatsApp.** Só em grupo: o resumo do grupo, com os mesmos campos de `GET /groups/{group_id}`.",
      "properties": {
        "is_admin": {
          "type": "boolean",
          "description": "A inbox é administradora."
        },
        "is_member": {
          "type": "boolean",
          "description": "A inbox ainda participa."
        },
        "announce": {
          "type": "boolean",
          "description": "Só administradores mandam mensagem."
        },
        "community": {
          "type": "boolean",
          "description": "É uma comunidade."
        },
        "parent_community": {
          "type": "object",
          "description": "A comunidade a que o grupo pertence.",
          "additionalProperties": false,
          "required": [
            "id"
          ],
          "properties": {
            "id": {
              "type": "string",
              "description": "Id da comunidade (`<id>@g.us`)."
            },
            "name": {
              "type": "string",
              "description": "Nome da comunidade, quando conhecido."
            },
            "picture_url": {
              "type": "string",
              "description": "Foto completa, quando conhecida."
            },
            "picture_preview_url": {
              "type": "string",
              "description": "Miniatura da foto, quando conhecida (use nas listas)."
            },
            "default_subgroup_id": {
              "type": "string",
              "description": "Id do grupo de avisos da comunidade, quando conhecido."
            }
          }
        }
      },
      "x-only": "whatsapp"
    },
    "lead_id": {
      "type": "string",
      "description": "Id do lead do contato. Toda conversa direta tem; grupo, canal e status não."
    },
    "lead": {
      "$ref": "#/components/schemas/OrkesioLead",
      "description": "O CRM do contato da conversa (no `GET /chats`, no `GET /chats/{chat_id}` e no `chat.updated`). Em `message.received` e `message.sent`, vem ao lado da conversa, em `data.lead`. Ausente em grupo, canal e status."
    },
    "automation_paused_until": {
      "description": "Pausada até (ISO), `forever` (até alguém religar) ou ausente (ligada).",
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "string",
          "const": "forever"
        }
      ]
    },
    "automation_pause_reason": {
      "type": "string",
      "description": "Por que a automação pausou sozinha: pedido de humano (IA ou fluxo) ou limite de respostas da IA. Ausente quando foi pausada à mão ou está ligada."
    },
    "ai_memory_from": {
      "type": "string",
      "format": "date-time",
      "description": "A IA lê a conversa só a partir daqui; ausente = toda a conversa."
    },
    "notes": {
      "type": "string",
      "description": "A anotação da conversa (as notas do WhatsApp Business). Sem anotação: ausente na lista e nos eventos, vazia no `GET /chats/{chat_id}`."
    },
    "automation": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "active"
      ],
      "description": "Se a IA atende a conversa agora: a IA ligada, a conversa sem pausa e sem fluxo esperando resposta, e o gatilho que pegaria a próxima mensagem do contato (o de maior prioridade, sem palavra-chave, cujo filtro combina) é de um agente. Vem em `GET /chats`, `GET /chats/{chat_id}`, `message.received` e `message.sent`. Nos eventos, fica de fora quando não deu para ler a tempo (vem na próxima mensagem e no `GET /chats`); o `chat.updated` não traz.",
      "properties": {
        "active": {
          "type": "boolean",
          "description": "A IA responde a próxima mensagem do contato."
        },
        "agent": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "id"
          ],
          "description": "O agente que atende (com `active`).",
          "properties": {
            "id": {
              "type": "string",
              "description": "Id do agente (`/chatbot/agents`)."
            },
            "name": {
              "type": "string",
              "description": "Nome do agente."
            }
          }
        }
      }
    },
    "post": {
      "type": "object",
      "additionalProperties": false,
      "description": "Só em `type: post` (Instagram e Messenger), e só no `GET /chats/{chat_id}`: o post comentado, buscado na Meta na hora. A lista e os eventos trazem só o nome (o começo da legenda) e a foto (a miniatura). Os comentários são as mensagens da conversa; a resposta a outro comentário vem em `reply_to`.",
      "properties": {
        "url": {
          "type": "string",
          "description": "Link do post (permalink)."
        },
        "caption": {
          "type": "string",
          "description": "Legenda (no Facebook, o texto do post)."
        },
        "media_type": {
          "type": "string",
          "description": "Instagram: `image`, `video` ou `carousel_album`; `reels` e `ad` vêm em `product_type`."
        },
        "product_type": {
          "type": "string",
          "description": "Só Instagram: `feed`, `reels` ou `ad`."
        },
        "thumbnail_url": {
          "type": "string",
          "description": "Miniatura (pode expirar)."
        },
        "created_at": {
          "type": "string",
          "format": "date-time",
          "description": "Quando o post foi publicado."
        }
      }
    },
    "ad": {
      "type": "object",
      "additionalProperties": false,
      "description": "O último clique em anúncio que trouxe o contato (anúncio de \"enviar mensagem\" no WhatsApp, no Messenger ou no Instagram): os campos do `referral` da mensagem que veio do anúncio, mais `clicked_at`. Fica na conversa mesmo depois que as mensagens antigas são apagadas; outro clique mais novo troca. Ausente se o contato nunca veio de anúncio. Use o `ctwa_clid` para mandar conversões para a Meta ([Conversões para a Meta](/docs/conversoes-meta)).",
      "properties": {
        "source_type": {
          "type": "string",
          "description": "Tipo da origem informado pela Meta: `ad` (anúncio) ou `post` (publicação).",
          "enum": [
            "ad",
            "post"
          ]
        },
        "source_id": {
          "type": "string",
          "description": "Id do anúncio ou da publicação na Meta."
        },
        "source_url": {
          "type": "string",
          "description": "Link do anúncio ou da publicação."
        },
        "headline": {
          "type": "string",
          "description": "Título do anúncio."
        },
        "body": {
          "type": "string",
          "description": "Texto do anúncio."
        },
        "media_type": {
          "type": "string",
          "enum": [
            "image",
            "video"
          ],
          "description": "Mídia do anúncio."
        },
        "media_url": {
          "type": "string",
          "description": "Link da imagem ou do vídeo do anúncio."
        },
        "thumbnail_url": {
          "type": "string",
          "description": "Miniatura do anúncio."
        },
        "ctwa_clid": {
          "type": "string",
          "description": "Id do clique no anúncio (click-to-WhatsApp). É o que se devolve à Meta (API de Conversões) para atribuir venda ou lead ao anúncio. Não vem em anúncio de Status."
        },
        "welcome_message": {
          "type": "string",
          "description": "Mensagem de boas-vindas configurada no anúncio, quando houver."
        },
        "clicked_at": {
          "type": "string",
          "format": "date-time",
          "description": "Quando chegou a mensagem do clique."
        }
      }
    }
  },
  "required": [
    "id",
    "type"
  ],
  "additionalProperties": false,
  "description": "Conversa. Em grupo, `id` e `name` identificam o grupo, e quem escreveu vem no `author` da mensagem. Em `message.received` e `message.sent` (webhook e `/events`), `data.chat` traz o resumo da conversa, como no `GET /chats/{chat_id}` (o `lead` vem ao lado, em `data.lead`): não lidas, arquivada, etiquetas, pausa da automação, `automation`, janela de resposta, `lead_id`. Sob carga, o resumo pode ser o de antes desta mensagem. Nos outros eventos de mensagem, só `id`, `lid`, `type` e `name`: o estado muda em `chat.updated` e vem no histórico."
}
```

## #/components/schemas/OrkesioParticipant

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Identificador da pessoa no canal (opaco). No WhatsApp é `<número>@s.whatsapp.net` ou `<BSUID>@bsuid`; em outros canais, o id deles. Não conte com ele ser telefone: use `phone`."
    },
    "phone": {
      "type": "string",
      "description": "Telefone (só dígitos), quando o canal informa."
    },
    "username": {
      "type": "string",
      "description": "Nome de usuário (@), quando o canal informa."
    },
    "lid": {
      "type": "string",
      "description": "**Só WhatsApp.** LID, quando conhecido.",
      "x-only": "whatsapp"
    },
    "name": {
      "type": "string",
      "description": "Nome visível (push name), quando conhecido."
    },
    "picture_url": {
      "type": "string",
      "description": "Foto de perfil, quando conhecida."
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false,
  "description": "Pessoa: autor de mensagem, participante de grupo, quem fez uma ação."
}
```

## #/components/schemas/OrkesioLead

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Id do lead na Orkesio. Opaco: guarde como veio, sem montar a partir de outro campo. Hoje é o id interno da conversa onde o lead nasceu."
    },
    "phone": {
      "type": "string",
      "description": "Telefone do contato com DDI (só dígitos), quando conhecido."
    },
    "lid": {
      "type": "string",
      "description": "LID do contato, quando conhecido (só no `whatsapp_web`)."
    },
    "name": {
      "type": "string",
      "description": "Como o contato quer ser chamado (ex.: `Dona Maria`), escrito por você, pela IA ou por um fluxo. Não vem do WhatsApp: os nomes do WhatsApp são `contact_name` e `push_name` da conversa."
    },
    "full_name": {
      "type": "string",
      "description": "Nome completo, para cadastro (nota, contrato), escrito por você, pela IA ou por um fluxo. Não vem do WhatsApp."
    },
    "email": {
      "type": "string",
      "description": "E-mail."
    },
    "document": {
      "type": "string",
      "description": "Documento (CPF/CNPJ ou outro)."
    },
    "status": {
      "type": "string",
      "description": "Etapa do funil, texto livre. A coluna do kanban é outra coisa: a tag com `kanban: true` em `tags`."
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string",
        "description": "Etiqueta do lead."
      },
      "description": "Etiquetas do lead (do CRM, não as do WhatsApp Business)."
    },
    "fields": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      },
      "description": "Campos personalizados (até 20), pela chave (`field01` a `field20`). O nome de cada um está em `GET /leads/fields`."
    },
    "notes": {
      "type": "string",
      "description": "Notas do CRM, só na Orkesio. Não são as notas do WhatsApp Business (essas são da conversa, em `GET /chats/{chat_id}`)."
    },
    "kanban_order": {
      "type": "integer",
      "description": "Posição do cartão na coluna do kanban (maior aparece primeiro)."
    },
    "identities": {
      "type": "array",
      "description": "As contas do contato em cada canal: uma por conversa ligada ao lead.",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "channel",
          "id"
        ],
        "properties": {
          "channel": {
            "type": "string",
            "enum": [
              "whatsapp",
              "telegram",
              "messenger",
              "instagram"
            ],
            "description": "A rede (o WhatsApp Web e a API oficial são a mesma rede: `whatsapp`)."
          },
          "id": {
            "type": "string",
            "description": "O id do contato nesse canal, o mesmo de `chat.id`."
          },
          "username": {
            "type": "string",
            "description": "O nome de usuário nesse canal, quando há."
          }
        }
      }
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false,
  "description": "Lead do CRM: o contato, com um lead por contato e por dono (hoje a inbox, então um por conversa direta). Grupo, canal e status não têm lead. Vem sempre em `message.received` e `message.sent` de conversa direta, e em cada conversa direta de `GET /chats`."
}
```

## #/components/schemas/OrkesioError

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Código estável do erro, em inglês e `snake_case`. Os de uso geral: `invalid_request` (400): pedido inválido: JSON malformado, campo desconhecido ou valor fora do permitido (o detalhe em `message`; o campo em `field`, quando é um só); `unauthorized` (401): `token` ou `admintoken` ausente ou inválido; `forbidden` (403): o token não pode fazer isso (no servidor de demonstração, por exemplo); `not_admin` (403): o WhatsApp recusou por falta de permissão no grupo ou na newsletter; `account_restricted` (403): o WhatsApp restringiu a conta de iniciar conversas novas (mandar para quem já conversa continua valendo; até quando, em `GET /inbox/limits`); `new_chat_limit` (403): a conta atingiu a cota do WhatsApp de conversas novas neste ciclo (veja `GET /inbox/limits`); os dois também no `error` de `OrkesioMessage` e de `message.status`, e não adianta repetir o envio; `payment_required` (403): na API oficial, a Meta recusou o envio por um problema no pagamento da conta do WhatsApp Business (erro 131042 da Meta); acerte a forma de pagamento no gerenciador da Meta, porque repetir não adianta; também no `error` de `OrkesioMessage` e de `message.status`; `whatsapp_rejected` (400): o WhatsApp recusou a mudança pedida (o campo, em `field`, quando é um só); `not_found` (404): o recurso não existe nesta inbox; `conflict` (409): o recurso já existe ou mudou (id em uso, inbox de outro canal); `inbox_not_paired` (409): a inbox ainda não conectou um número; `payload_too_large` (413): o corpo passou do limite; `canceled` e `expired`: só no `error` de `OrkesioMessage` e de `message.status` (envio cancelado antes de sair, ou que passou do prazo na fila); `rate_limited` (429): muitos pedidos; espere o `Retry-After`; `internal_error` (500): falha inesperada na api; tente de novo; `send_failed` (500): o envio falhou (o motivo em `message`); também no `error` de `OrkesioMessage` e de `message.status`; `unsupported_for_channel` (501): o canal da inbox não atende esta rota ou este tipo de mensagem; `meta_error` (502): a Meta recusou ou não respondeu; `disconnected` (503): a inbox está desconectada (sem sessão do WhatsApp, ou token do canal oficial vencido); `unavailable` (503 ou 504): o WhatsApp não respondeu a tempo, ou algo em andamento impede agora; tente de novo. Cada rota lista os códigos próprios dela (`outside_window`, `number_invalid`, `flow_invalid`...). A lista pode crescer: trate código desconhecido pelo status HTTP."
    },
    "message": {
      "type": "string",
      "description": "Descrição para pessoas (às vezes o texto do WhatsApp ou da Meta). Não compare o texto: use `error`."
    },
    "field": {
      "type": "string",
      "description": "O campo do pedido que causou o erro, quando é um só (por exemplo, o campo que o WhatsApp recusou num `PATCH`)."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": true,
  "description": "O objeto de erro da Orkesio, o mesmo em todo lugar: o corpo das respostas de erro e o `error` de `OrkesioMessage`, `message.status` e `message.failed`. Algumas rotas juntam campos próprios (`request_id`, `errors`...)."
}
```

## #/components/responses/RateLimited

```json
{
  "description": "`rate_limited`: passou do limite de chamadas desta inbox (ou do admin); espere o tempo do header `Retry-After` e tente de novo.",
  "headers": {
    "Retry-After": {
      "description": "Segundos até poder chamar de novo.",
      "schema": {
        "type": "integer",
        "minimum": 1
      }
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OrkesioError"
      },
      "example": {
        "error": "rate_limited",
        "message": "Muitas requisições."
      }
    }
  }
}
```

## #/components/responses/InternalError

```json
{
  "description": "`internal_error`: falha inesperada na api (no banco, por exemplo); tente de novo.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OrkesioError"
      },
      "example": {
        "error": "internal_error",
        "message": "Falha inesperada."
      }
    }
  }
}
```

## #/components/responses/CloudUnsupported

```json
{
  "description": "`unsupported_for_channel`: o canal da inbox não atende esta rota (rota só do WhatsApp Web numa inbox oficial, ou rota da API oficial numa inbox do WhatsApp Web). O canal está em `Inbox.channel`.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OrkesioError"
      },
      "example": {
        "error": "unsupported_for_channel",
        "message": "Esta rota não está disponível no canal da inbox."
      }
    }
  }
}
```

## #/components/responses/Disconnected

```json
{
  "description": "`disconnected`: a inbox está desconectada do WhatsApp (a api esperou a sessão e tentou reconectar). `unavailable`: o WhatsApp não respondeu agora; tente de novo.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OrkesioError"
      },
      "example": {
        "error": "disconnected",
        "message": "Instância desconectada do WhatsApp."
      }
    }
  }
}
```

## Guias relacionados

[Visão geral](/docs/overview) · [O que funciona em cada canal](/docs/canais) · [O que muda da uazapi](/docs/o-que-muda)