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

# Iniciar conversa com um contato novo

> Único jeito de falar com alguém que nunca conversou com a empresa — acha ou cria o cliente pelo telefone, cria (ou reaproveita, se já houver uma aberta) a conversa, e envia a primeira mensagem.

Fora da janela de 24h de atendimento do WhatsApp, só `send_type: template` funciona — a Meta rejeita texto livre pra quem nunca recebeu mensagem sua. Use `GET /wba/templates?status=APPROVED` pra listar os templates aprovados disponíveis.

Cumprir a política de uso da Meta (destinatário deu opt-in, etc.) é responsabilidade de quem integra — a Nupapia repassa o erro da Meta tal como veio, sem validação própria.

Se a Meta recusar o envio, o cliente e a conversa **continuam existindo** (resposta `502` com os ids) — dá pra tentar de novo na mesma conversa via `POST /chat/conversations/{id}/wba-send-template` ou `POST /chat/conversations/{id}/messages`.




## OpenAPI

````yaml /api-reference/openapi.yaml post /chat/conversations/start-whatsapp
openapi: 3.0.3
info:
  title: Nupapia API — Integração
  version: '1.0'
  description: >
    Referência da API pública da Nupapia para integração de sistemas terceiros:
    conversas de chat e CRM (clientes). Gere um token de integração em
    **Configurações → Integrações** dentro da Nupapia e use-o como Bearer token
    em todas as chamadas abaixo.
servers:
  - url: https://api.nupapia.com.br/api
    description: Produção
security:
  - integrationToken: []
paths:
  /chat/conversations/start-whatsapp:
    post:
      tags:
        - Conversas
      summary: Iniciar conversa com um contato novo
      description: >
        Único jeito de falar com alguém que nunca conversou com a empresa — acha
        ou cria o cliente pelo telefone, cria (ou reaproveita, se já houver uma
        aberta) a conversa, e envia a primeira mensagem.


        Fora da janela de 24h de atendimento do WhatsApp, só `send_type:
        template` funciona — a Meta rejeita texto livre pra quem nunca recebeu
        mensagem sua. Use `GET /wba/templates?status=APPROVED` pra listar os
        templates aprovados disponíveis.


        Cumprir a política de uso da Meta (destinatário deu opt-in, etc.) é
        responsabilidade de quem integra — a Nupapia repassa o erro da Meta tal
        como veio, sem validação própria.


        Se a Meta recusar o envio, o cliente e a conversa **continuam
        existindo** (resposta `502` com os ids) — dá pra tentar de novo na mesma
        conversa via `POST /chat/conversations/{id}/wba-send-template` ou `POST
        /chat/conversations/{id}/messages`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - channel_id
                - phone
                - name
                - send_type
              properties:
                channel_id:
                  type: integer
                  description: >-
                    Canal de WhatsApp da empresa — veja GET
                    /company/{id}/channels.
                phone:
                  type: string
                  example: '+5511999999999'
                name:
                  type: string
                lastname:
                  type: string
                send_type:
                  type: string
                  enum:
                    - template
                    - text
                template_name:
                  type: string
                  description: Obrigatório se send_type=template.
                language:
                  type: string
                  example: pt_BR
                variables:
                  type: object
                  description: 'Atalho pras variáveis do template — mapa {"1": "valor"}.'
                text:
                  type: string
                  description: >-
                    Obrigatório se send_type=text. Só funciona dentro da janela
                    de 24h.
                topic:
                  type: string
                pipeline_id:
                  type: integer
                pipeline_stage_id:
                  type: integer
      responses:
        '201':
          description: Mensagem enviada
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      conversation_id:
                        type: string
                      client_id:
                        type: string
                      message_id:
                        type: integer
        '502':
          description: A Meta recusou o envio (cliente/conversa continuam criados)
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  meta:
                    type: object
                    description: Resposta crua da Meta
                  data:
                    type: object
                    properties:
                      conversation_id:
                        type: string
                      client_id:
                        type: string
components:
  securitySchemes:
    integrationToken:
      type: http
      scheme: bearer
      bearerFormat: Token de integração (gerado em Configurações → Integrações)

````