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

# Enviar mensagem

> Enfileira o envio de uma mensagem de texto, template ou mídia pelo canal associado à chave de API. O envio é **assíncrono**: a resposta retorna imediatamente um `requestId` para correlação, e o processamento acontece em background. O status de cada envio pode ser acompanhado nos logs da aba **API** do canal.

## Variáveis de template

As variáveis (`template.variables`) são agrupadas por componente (`header`, `body`, `buttons`). Cada item aceita três formatos:

| Formato                    | Exemplo                                           | Quando usar                                           |
| -------------------------- | ------------------------------------------------- | ----------------------------------------------------- |
| String posicional          | `"R$ 500,00"`                                     | Placeholders numerados (`{{1}}`, `{{2}}`...) na ordem |
| Objeto com `key`           | `{ "key": "valor_fatura", "value": "R$ 500,00" }` | Templates da Meta com variáveis nomeadas              |
| Objeto com `correlationId` | `{ "correlationId": 0, "value": "R$ 500,00" }`    | Formato legado por posição                            |

Um array simples no lugar do objeto (`"variables": ["R$ 500,00"]`) também é aceito e tratado como `body` (formato legado).

## Botão order\_details (Pix)

`template.buttons` serve para botões especiais montados pelo backend — hoje apenas `order_details` (cobrança Pix via WhatsApp):

```json theme={null}
{
  "buttons": [
    {
      "index": 0,
      "type": "order_details",
      "orderDetails": {
        "referenceId": "boleto-123456-20260402",
        "type": "digital-goods",
        "paymentType": "br",
        "currency": "BRL",
        "totalAmount": { "value": 50000, "offset": 100 },
        "paymentSettings": [
          {
            "type": "pix_dynamic_code",
            "pixDynamicCode": {
              "code": "00020101021226700014br.gov.bcb.pix...",
              "merchantName": "Zazz Internet",
              "key": "39580525000189",
              "keyType": "CNPJ"
            }
          }
        ],
        "order": {
          "status": "pending",
          "subtotal": { "value": 50000, "offset": 100 },
          "items": [
            {
              "retailerId": "1234567",
              "name": "Mensalidade",
              "amount": { "value": 50000, "offset": 100 },
              "quantity": 1
            }
          ]
        }
      }
    }
  ]
}
```

<Note>
  Valores monetários usam o menor valor da moeda com `offset` decimal: `{ "value": 50000, "offset": 100 }` = R\$ 500,00. O campo `value` também aceita string decimal de ERP (ex.: `"129,90"`), convertida automaticamente usando o `offset`. Placeholders **textuais** de botão continuam em `variables.buttons`.
</Note>

## Mídia

<Warning>
  Hoje o envio de mídia exige o conteúdo em `base64` (sem prefixo `data:`). O campo `mediaUrl` existe no schema, mas ainda não é aceito no processamento — requisições de mídia sem `base64` retornam `400 Base64 payload is required`.
</Warning>


## OpenAPI

````yaml POST /channel-api/messages/send
openapi: 3.1.0
info:
  title: Zazz Chat — Channel API
  description: >-
    API por canal do Zazz Chat para envio de mensagens e webhook de eventos. A
    autenticação usa uma chave de API por canal, gerada na interface do sistema.
  version: 1.0.0
servers:
  - url: https://{host}
    description: Back-end do Zazz Chat
    variables:
      host:
        default: chat.zazzinternet.com
        description: Host do back-end da sua instalação do Zazz Chat
security:
  - channelApiKey: []
paths:
  /channel-api/messages/send:
    post:
      summary: Enviar mensagem
      description: >-
        Enfileira o envio de uma mensagem de texto, template ou mídia pelo canal
        associado à chave de API. O envio é **assíncrono**: a resposta retorna
        imediatamente um `requestId` para correlação, e o processamento acontece
        em background. O status de cada envio pode ser acompanhado nos logs da
        aba **API** do canal.
      operationId: sendChannelMessage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendMessageRequest'
            examples:
              texto:
                summary: Mensagem de texto
                value:
                  contact:
                    value: '554396647639'
                    name: Cliente
                  message:
                    type: text
                    text:
                      value: Olá! Sua fatura foi gerada.
                  metadata:
                    erpInvoiceId: '123456'
              template:
                summary: Mensagem de template
                value:
                  contact:
                    value: '554396647639'
                  message:
                    type: template
                    template:
                      name: faturamento_do_boleto
                      language: pt_BR
                      variables:
                        header:
                          - value: ABC123
                        body:
                          - key: valor_fatura
                            value: R$ 500,00
                          - key: vencimento
                            value: 10/08/2026
                      mediaHeader:
                        format: document
                        link: https://example.com/boleto.pdf
                        filename: boleto.pdf
              midia:
                summary: Mensagem de mídia
                value:
                  contact:
                    value: '554396647639'
                  message:
                    type: media
                    media:
                      mimetype: application/pdf
                      filename: boleto.pdf
                      caption: Segue o boleto.
                      base64: JVBERi0xLjQK...
                      mediaType: document
      responses:
        '201':
          description: Mensagem enfileirada com sucesso.
          content:
            application/json:
              schema:
                type: object
                required:
                  - requestId
                properties:
                  requestId:
                    type: string
                    format: uuid
                    description: >-
                      Identificador único da requisição, usado para correlação
                      nos logs da aba API do canal.
                    example: 3f2b4c1e-8a9d-4e2f-b1c3-9d8e7f6a5b4c
        '400':
          description: >-
            Requisição inválida: header `x-channel-api-key` ausente, corpo mal
            formado ou campo obrigatório do tipo de mensagem faltando (ex.:
            `template.name`, `media.base64`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                statusCode: 400
                message: Base64 payload is required
                error: Bad Request
        '404':
          description: Chave de API inválida ou API desabilitada no canal.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                statusCode: 404
                message: Invalid API token
                error: Not Found
components:
  schemas:
    SendMessageRequest:
      type: object
      required:
        - contact
        - message
      properties:
        contact:
          $ref: '#/components/schemas/Contact'
        message:
          $ref: '#/components/schemas/Message'
        flowId:
          type: string
          description: Identificador opcional de fluxo para correlação externa.
          example: flow-123
        closeConversation:
          type: boolean
          default: false
          description: >-
            Se `true`, encerra a conversa aberta do contato nesse canal antes de
            enviar a nova mensagem.
        metadata:
          type: object
          additionalProperties:
            type: string
          description: >-
            Metadados livres de correlação externa (chave/valor em string).
            Ficam registrados no log da requisição.
          example:
            erpInvoiceId: '123456'
    Error:
      type: object
      properties:
        statusCode:
          type: integer
        message:
          type: string
        error:
          type: string
    Contact:
      type: object
      required:
        - value
      properties:
        value:
          type: string
          description: >-
            Identificador do destinatário. Para WhatsApp, o telefone com DDI e
            DDD.
          example: '554396647639'
        type:
          type: string
          enum:
            - phone
            - email
          default: phone
          description: Tipo do contato para normalização. Se omitido, assume `phone`.
        name:
          type: string
          description: >-
            Nome amigável do destinatário. Usado apenas para contexto da
            requisição.
          example: Cliente
    Message:
      type: object
      required:
        - type
      description: >-
        Mensagem a ser enviada. O objeto correspondente ao `type` escolhido
        (`text`, `template` ou `media`) é obrigatório.
      properties:
        type:
          type: string
          enum:
            - text
            - template
            - media
          description: Tipo da mensagem.
        text:
          $ref: '#/components/schemas/TextMessage'
        template:
          $ref: '#/components/schemas/TemplateMessage'
        media:
          $ref: '#/components/schemas/MediaMessage'
    TextMessage:
      type: object
      required:
        - value
      description: >-
        Payload da mensagem de texto. Obrigatório quando `message.type =
        "text"`.
      properties:
        value:
          type: string
          description: Texto da mensagem.
          example: Olá, mundo
        pushName:
          type: string
          description: Push name opcional usado no contexto interno da mensagem.
          example: API
    TemplateMessage:
      type: object
      required:
        - name
      description: >-
        Payload da mensagem de template. Obrigatório quando `message.type =
        "template"`.
      properties:
        name:
          type: string
          description: Nome do template aprovado no provider.
          example: faturamento_do_boleto
        language:
          type: string
          default: pt_BR
          description: Idioma do template. Se omitido, usa `pt_BR`.
        variables:
          $ref: '#/components/schemas/TemplateVariables'
        mediaHeader:
          $ref: '#/components/schemas/TemplateMediaHeader'
        buttons:
          type: array
          items:
            $ref: '#/components/schemas/TemplateButton'
          description: >-
            Botões especiais montados pelo backend (hoje apenas
            `order_details`). Placeholders textuais de botão continuam em
            `variables.buttons`.
    MediaMessage:
      type: object
      required:
        - mimetype
        - base64
      description: >-
        Payload da mensagem de mídia. Obrigatório quando `message.type =
        "media"`. Hoje o envio exige o conteúdo em `base64`; o campo `mediaUrl`
        existe no schema mas ainda não é aceito no processamento.
      properties:
        mimetype:
          type: string
          description: Mimetype da mídia enviada.
          example: application/pdf
        base64:
          type: string
          description: Conteúdo do arquivo em base64, sem prefixo `data:`. Obrigatório.
        filename:
          type: string
          description: Nome do arquivo.
          example: boleto.pdf
        caption:
          type: string
          description: Legenda da mídia, quando o provider suporta.
          example: Segue o boleto.
        mediaUrl:
          type: string
          description: >-
            Reservado. URL pública da mídia — ainda não aceito no processamento;
            envie `base64`.
        mediaType:
          type: string
          description: Tipo lógico usado ao persistir a mensagem.
          example: document
    TemplateVariables:
      type: object
      description: >-
        Variáveis do template agrupadas por componente. Um array simples no
        lugar deste objeto também é aceito e tratado como `body` (formato
        legado).
      properties:
        header:
          type: array
          items:
            $ref: '#/components/schemas/TemplateVariableValue'
          description: Valores do header do template.
        body:
          type: array
          items:
            $ref: '#/components/schemas/TemplateVariableValue'
          description: Valores do body do template.
        buttons:
          type: array
          items:
            $ref: '#/components/schemas/TemplateVariableValue'
          description: >-
            Valores de placeholders textuais em botões do template. Não use este
            campo para `order_details`.
    TemplateMediaHeader:
      type: object
      required:
        - format
      description: >-
        Header de mídia do template, quando existir componente de mídia. Informe
        `link` (URL pública HTTPS) ou `fileId` (mídia já existente no provider).
      properties:
        format:
          type: string
          enum:
            - image
            - video
            - document
          description: Tipo do header de mídia.
        fileId:
          type: string
          description: ID já existente de mídia no provider, quando aplicável.
          example: '1234567890'
        link:
          type: string
          description: URL pública HTTPS do arquivo a ser usado no header.
          example: https://example.com/boleto.pdf
        filename:
          type: string
          description: Nome do arquivo enviado ao provider quando o formato for `document`.
          example: boleto.pdf
    TemplateButton:
      type: object
      required:
        - index
        - type
        - orderDetails
      properties:
        index:
          type: number
          description: Índice do botão dentro do template aprovado pela Meta.
          example: 0
        type:
          type: string
          enum:
            - order_details
          description: Tipo do botão especial montado pelo backend.
        orderDetails:
          $ref: '#/components/schemas/OrderDetails'
    TemplateVariableValue:
      oneOf:
        - type: string
          description: 'Forma curta posicional: apenas o valor do placeholder, na ordem.'
        - type: object
          required:
            - value
          properties:
            key:
              type: string
              description: >-
                Nome da variável nomeada no template da Meta. Quando informado,
                o sistema envia `parameter_name` no parâmetro correspondente.
              example: valor_fatura
            correlationId:
              type: number
              description: >-
                Posição legada do placeholder no componente. Usado quando `key`
                não é informado.
              example: 0
            value:
              type: string
              description: Valor final enviado para o placeholder do template.
              example: R$ 500,00
    OrderDetails:
      type: object
      required:
        - referenceId
        - type
        - paymentType
        - currency
        - totalAmount
        - paymentSettings
        - order
      description: >-
        Payload semântico do botão de `order_details` (ex.: cobrança Pix via
        WhatsApp).
      properties:
        referenceId:
          type: string
          description: Identificador único da cobrança/pedido no sistema emissor.
          example: boleto-123456-20260402
        type:
          type: string
          description: Tipo do pedido aceito pelo provider.
          example: digital-goods
        paymentType:
          type: string
          description: Método/região de pagamento configurado no provider.
          example: br
        currency:
          type: string
          description: Moeda do pedido.
          example: BRL
        totalAmount:
          $ref: '#/components/schemas/Amount'
        paymentSettings:
          type: array
          items:
            $ref: '#/components/schemas/PaymentSetting'
          description: Configurações de pagamento disponibilizadas para a cobrança.
        order:
          $ref: '#/components/schemas/OrderPayload'
    Amount:
      type: object
      required:
        - value
        - offset
      description: >-
        Valor monetário no menor valor da moeda com offset decimal. `{ "value":
        50000, "offset": 100 }` = R$ 500,00.
      properties:
        value:
          oneOf:
            - type: integer
            - type: string
          description: >-
            Valor no menor valor da moeda. Aceita inteiro já normalizado (ex.:
            `12990`) ou string decimal de ERP (ex.: `"129,90"`), convertida
            automaticamente usando o `offset`.
          example: 50000
        offset:
          type: integer
          description: >-
            Offset decimal usado pelo provider. Ex.: `100` representa 2 casas
            decimais.
          example: 100
    PaymentSetting:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - pix_dynamic_code
          description: Tipo da configuração de pagamento.
        pixDynamicCode:
          $ref: '#/components/schemas/PixDynamicCode'
    OrderPayload:
      type: object
      required:
        - status
        - items
        - subtotal
      properties:
        status:
          type: string
          description: Status atual do pedido enviado ao cliente.
          example: pending
        items:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/OrderItem'
          description: Itens do pedido.
        subtotal:
          $ref: '#/components/schemas/Amount'
        tax:
          $ref: '#/components/schemas/OrderTax'
    PixDynamicCode:
      type: object
      required:
        - code
        - merchantName
        - key
        - keyType
      description: >-
        Configuração do Pix dinâmico. Obrigatória quando `type =
        "pix_dynamic_code"`.
      properties:
        code:
          type: string
          description: Código Pix dinâmico completo retornado pelo PSP.
          example: 00020101021226700014br.gov.bcb.pix2548pix.example.com...
        merchantName:
          type: string
          description: Nome do recebedor exibido pelo provedor de pagamentos.
          example: Zazz Internet
        key:
          type: string
          description: Chave Pix usada na cobrança.
          example: '39580525000189'
        keyType:
          type: string
          description: Tipo da chave Pix.
          example: CNPJ
    OrderItem:
      type: object
      required:
        - retailerId
        - name
        - amount
        - quantity
      properties:
        retailerId:
          type: string
          description: ID estável do item no sistema do emissor.
          example: '1234567'
        name:
          type: string
          description: Nome exibido do item.
          example: Mensalidade
        amount:
          $ref: '#/components/schemas/Amount'
        quantity:
          type: number
          description: Quantidade do item.
          example: 1
    OrderTax:
      type: object
      required:
        - value
        - offset
      description: Dados de imposto do pedido.
      properties:
        value:
          oneOf:
            - type: integer
            - type: string
          description: Valor do imposto no menor valor da moeda.
        offset:
          type: integer
          description: Offset decimal usado pelo provider.
          example: 100
        description:
          type: string
          description: Descrição opcional do imposto.
  securitySchemes:
    channelApiKey:
      type: apiKey
      in: header
      name: x-channel-api-key
      description: >-
        Chave de API do canal, gerada na aba **API** das configurações do canal
        (Dashboard → Suporte → Canais). A chave é exibida uma única vez ao ser
        gerada; gerar uma nova invalida a anterior.

````