> ## Documentation Index > Fetch the complete documentation index at: https://docs.blu.direct/llms.txt > Use this file to discover all available pages before exploring further. # Abrir uma conversa > Abre a conversa entre um dos seus números e um número de WhatsApp, como ao iniciar uma conversa com um número no app do WhatsApp. Se a conversa já existir, ela é devolvida com status `200` em vez de `201`. ## OpenAPI ````yaml /api/openapi.yaml post /v1/chats openapi: 3.1.0 info: title: API do blü version: '2026-10-11' summary: >- Envie e receba mensagens no WhatsApp, faça campanhas e gerencie agentes de IA. description: > A API do blü segue o modelo REST. Ela usa URLs previsíveis e orientadas a recursos, recebe corpos de requisição em JSON, devolve respostas em JSON e usa códigos de status, autenticação e métodos HTTP padrão. ## Vocabulário A API usa os mesmos termos do WhatsApp. Um **número** é um número de WhatsApp conectado à sua conta. Um **contato** é uma pessoa, única por conta e por `wa_id`. Uma **conversa** liga um dos seus números a um `wa_id` e reúne as **mensagens** trocadas entre eles. Uma **campanha** envia uma mensagem para vários contatos. ## Tipos de plataforma Os números usam a API do WhatsApp Cloud, da Meta, e são conectados no painel do blü. O campo `capabilities` do número informa o que ele permite, e a API devolve um `whatsapp_error` com um `code` específico quando a requisição não segue uma regra. ## Convenções - **Ids** são opacos e começam com um prefixo do tipo de objeto, como `pn_`, `chat_` ou `msg_`. - Todo objeto tem `id`, `object` e `created` (em segundos Unix). - `POST` cria e atualiza; `DELETE` exclui. Ações são verbos no recurso, como `POST /v1/broadcasts/{id}/send`. - **Listas** são paginadas por cursor com `limit`, `starting_after` e `ending_before`, e devolvem um objeto de lista com `has_more`. - **Expansão**: campos que guardam um id podem ser trocados pelo objeto completo com `expand[]`, como `expand[]=contact` em uma conversa. - **Idempotência**: envie o cabeçalho `Idempotency-Key` em qualquer `POST` para repetir a requisição com segurança. As chaves ficam guardadas por 24 horas. - **Versionamento**: o cabeçalho `Blu-Version` escolhe a versão da API. Sem ele, vale a versão fixada na sua conta no primeiro uso. - **Metadados**: contatos, conversas, mensagens, campanhas e endpoints de webhook aceitam até 50 pares de chave e valor seus, em texto. contact: name: blü url: https://blu.direct/api servers: - url: https://api.blu.direct security: - secretKey: [] tags: - name: Conta description: A conta à qual sua chave de API pertence. - name: Números description: Números de WhatsApp conectados à sua conta e a conexão deles. - name: Contatos description: Pessoas com quem você conversa, únicas por conta e por `wa_id`. - name: Conversas description: Conversas entre um dos seus números e um `wa_id`. - name: Mensagens description: Mensagens enviadas e recebidas em uma conversa. - name: Mídia description: Arquivos usados em mensagens, campanhas e modelos. - name: Etiquetas description: Etiquetas que organizam contatos e definem o público de campanhas. - name: Modelos de mensagem description: >- Mensagens reutilizáveis. Obrigatórias em números `cloud_api` fora da janela de atendimento. - name: Campanhas description: Uma mensagem enviada para vários contatos, com intervalos entre os envios. - name: Agentes description: Agentes de IA que respondem às conversas. - name: Eventos description: Acontecimentos na sua conta, também enviados aos endpoints de webhook. - name: Endpoints de webhook description: URLs que recebem eventos. paths: /v1/chats: parameters: - $ref: '#/components/parameters/BluVersion' post: tags: - Conversas summary: Abrir uma conversa description: | Abre a conversa entre um dos seus números e um número de WhatsApp, como ao iniciar uma conversa com um número no app do WhatsApp. Se a conversa já existir, ela é devolvida com status `200` em vez de `201`. operationId: createChat parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: - phone_number - phone properties: phone_number: type: string pattern: ^pn_ phone: description: O número da outra pessoa no formato E.164, ou um `wa_id`. type: string examples: - '+5511988887777' metadata: $ref: '#/components/schemas/Metadata' responses: '200': description: A conversa já existia. content: application/json: schema: $ref: '#/components/schemas/Chat' '201': description: A conversa foi criada. content: application/json: schema: $ref: '#/components/schemas/Chat' 4XX: $ref: '#/components/responses/Error' 5XX: $ref: '#/components/responses/Error' components: parameters: BluVersion: name: Blu-Version in: header description: A versão da API a usar. Por padrão, é a versão fixada na sua conta. schema: type: string examples: - '2026-10-11' IdempotencyKey: name: Idempotency-Key in: header description: >- Uma chave única, como um UUID, que torna seguro repetir esta requisição por 24 horas. schema: type: string maxLength: 255 schemas: Metadata: description: >- Até 50 pares de chave e valor seus. Chaves com até 40 caracteres e valores com até 500. type: object maxProperties: 50 propertyNames: maxLength: 40 additionalProperties: type: string maxLength: 500 Chat: type: object required: - id - object - phone_number - wa_id - type - name - contact - last_message_at - service_window_expires_at - created - metadata properties: id: type: string pattern: ^chat_ examples: - chat_Q8x2 object: type: string const: chat phone_number: description: O seu número nesta conversa. Expansível. anyOf: - type: string pattern: ^pn_ - $ref: '#/components/schemas/PhoneNumber' wa_id: description: A outra parte. Ids de grupo terminam em `@g.us`. type: string examples: - '5511988887777' type: type: string enum: - individual - group name: description: >- O nome do contato, o nome de perfil no WhatsApp ou o assunto do grupo. type: - string - 'null' contact: description: O contato deste `wa_id`. Nulo em grupos. Expansível. anyOf: - type: string pattern: ^cont_ - $ref: '#/components/schemas/Contact' - type: 'null' last_message_at: type: - integer - 'null' service_window_expires_at: description: | Quando mensagens livres deixam de ser permitidas, 24 horas após a última mensagem do contato. Nulo quando a janela está fechada. type: - integer - 'null' created: $ref: '#/components/schemas/Timestamp' metadata: $ref: '#/components/schemas/Metadata' PhoneNumber: type: object required: - id - object - name - display_phone_number - wa_id - verified_name - platform_type - status - quality_rating - capabilities - agent - created properties: id: type: string pattern: ^pn_ examples: - pn_8f3aK1 object: type: string const: phone_number name: description: O nome que você deu ao número. type: string display_phone_number: type: - string - 'null' examples: - +55 11 99999-8888 wa_id: description: Nulo até o número ser conectado pela primeira vez. type: - string - 'null' examples: - '5511999998888' verified_name: description: O nome comercial ou de perfil no WhatsApp. type: - string - 'null' platform_type: $ref: '#/components/schemas/PlatformType' status: $ref: '#/components/schemas/PhoneNumberStatus' quality_rating: description: >- A classificação de qualidade da Meta. Nula até a Meta classificar o número. type: - string - 'null' enum: - GREEN - YELLOW - RED - UNKNOWN - null capabilities: $ref: '#/components/schemas/PhoneNumberCapabilities' agent: description: O agente que responde às conversas deste número. Expansível. anyOf: - type: string pattern: ^agent_ - $ref: '#/components/schemas/Agent' - type: 'null' created: $ref: '#/components/schemas/Timestamp' Contact: type: object required: - id - object - wa_id - profile - labels - opted_out - opted_out_at - marketing_stopped - created - metadata properties: id: type: string pattern: ^cont_ examples: - cont_7Hk1 object: type: string const: contact wa_id: type: string examples: - '5511988887777' profile: $ref: '#/components/schemas/ContactProfile' labels: description: As etiquetas do contato. Expansível. type: array items: anyOf: - type: string pattern: ^lbl_ - $ref: '#/components/schemas/Label' opted_out: description: >- O contato pediu para não receber mensagens. As campanhas o pulam em todos os números. type: boolean opted_out_at: type: - integer - 'null' marketing_stopped: description: >- O contato bloqueou mensagens de marketing no WhatsApp. Campanhas de marketing o pulam. type: boolean created: $ref: '#/components/schemas/Timestamp' metadata: $ref: '#/components/schemas/Metadata' Timestamp: description: Horário Unix em segundos. type: integer examples: - 1760190012 ErrorResponse: type: object required: - error properties: error: $ref: '#/components/schemas/Error' PlatformType: description: | A plataforma do número. Hoje, todos os números usam a API do WhatsApp Cloud, da Meta. type: string enum: - cloud_api PhoneNumberStatus: description: | `pending_link` nunca foi conectado. `connecting` está conectando ou reconectando. `connected` pode enviar e receber. `disconnected` foi desconectado e precisa ser conectado de novo. type: string enum: - pending_link - connecting - connected - disconnected PhoneNumberCapabilities: description: >- O que este número permite. Confira antes de usar recursos que mudam conforme o tipo de plataforma. type: object required: - chats - free_form_messages - polls - view_once - delivery_receipts properties: chats: description: Se as conversas e mensagens dele estão disponíveis pela API. type: boolean free_form_messages: description: >- `always` (sempre) ou `service_window` (só dentro da janela de atendimento de 24 horas após a última mensagem do contato). type: string enum: - always - service_window polls: type: boolean view_once: type: boolean delivery_receipts: description: Se as mensagens informam `delivered` e `read`. type: boolean Agent: type: object required: - id - object - name - instructions - faq - created properties: id: type: string pattern: ^agent_ examples: - agent_12Rf object: type: string const: agent name: type: string instructions: description: Como o agente deve se comportar e o que ele sabe. type: string faq: type: array items: $ref: '#/components/schemas/AgentFaqEntry' created: $ref: '#/components/schemas/Timestamp' ContactProfile: type: object additionalProperties: false properties: name: type: - string - 'null' maxLength: 200 Label: type: object required: - id - object - name - color - created properties: id: type: string pattern: ^lbl_ examples: - lbl_vip object: type: string const: label name: type: string color: $ref: '#/components/schemas/LabelColor' created: $ref: '#/components/schemas/Timestamp' Error: type: object required: - type - message - request_id properties: type: type: string enum: - invalid_request_error - authentication_error - permission_error - whatsapp_error - rate_limit_error - api_error code: description: | Um texto curto que identifica o erro específico, quando houver. - `whatsapp_error`: `phone_number_disconnected`, `not_on_whatsapp`, `outside_service_window`, `template_not_approved`, `unsupported_for_platform_type`, `contact_opted_out`, `marketing_stopped`, `media_too_large`. - `invalid_request_error`: `parameter_missing`, `parameter_invalid`, `resource_missing`, `idempotency_key_reused`, `broadcast_not_draft`, `consent_required`, `plan_limit_reached`. type: string examples: - outside_service_window message: description: Uma mensagem legível para pessoas. type: string param: description: O parâmetro da requisição relacionado ao erro, se houver. type: string examples: - text.body doc_url: type: string format: uri request_id: type: string AgentFaqEntry: type: object additionalProperties: false required: - question - answer properties: question: type: string answer: type: string LabelColor: description: Uma cor em hexadecimal. type: string pattern: ^#[0-9a-fA-F]{6}$ examples: - '#25D366' responses: Error: description: > A requisição falhou. Códigos de status: `400` requisição inválida, `401` chave de API inválida, `403` a chave não tem a permissão, `404` não encontrado, `409` conflito (como uma `Idempotency-Key` reutilizada com parâmetros diferentes), `422` uma regra do WhatsApp recusou a requisição, `429` limite de requisições atingido, `5xx` erro do lado do blü. headers: Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: RequestId: description: Identifica a requisição. Informe esse valor ao falar com o suporte. schema: type: string securitySchemes: secretKey: type: http scheme: bearer description: | Autentique com uma chave secreta (`sk_live_…`) ou uma chave restrita (`rk_live_…`) criada no painel. Chaves restritas só têm as permissões escolhidas na criação, como `messages:send`, `chats:read` ou `broadcasts:send`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.