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

# Enviar mensagem, resposta rápida ou template

> Envia uma mensagem (texto ou mídia), uma resposta rápida ou um template com parâmetros, header de mídia e botões.

<Info>
  **Endpoint** · `POST /conversation/actions`
</Info>

Envia uma mensagem. Cada ação envia **um único tipo de conteúdo**: texto, mídia, uma resposta rápida ou um template. Um texto, mídia ou resposta rápida pode também levar um template para quando a janela de 24h estiver fechada (veja abaixo).

<Tabs>
  <Tab title="Texto">
    ```jsonc theme={null}
    {
      "type": "send_message",
      "body": "Olá 👋"
    }
    ```

    Texto simples, até 4096 caracteres.
  </Tab>

  <Tab title="Mídia">
    ```jsonc theme={null}
    {
      "type": "send_message",
      "file_uuid": "7b8a1c2d-3e4f-5678-90ab-cdef12345678",
      "body": "Seu comprovante 📄",
      // Apenas se a visão não puder transcrever o arquivo (ver abaixo).
      "transcription": "Comprovante de pagamento de $500 de 12 de março"
    }
    ```

    O `file_uuid` vem do fluxo de [Enviar mídia](/pt/action-groups/upload-media). O
    `body` é uma legenda opcional; o áudio não admite legenda. A `transcription` é
    **obrigatória** quando a visão não pode transcrever o arquivo (tipo não suportado, ou
    maior que 20 MB); a resposta de `/files/confirm` antecipa isso com `requires_transcription`.
    Se faltar nesse caso, a ação falha com `TRANSCRIPTION_REQUIRED`.
  </Tab>

  <Tab title="Resposta rápida">
    ```jsonc theme={null}
    {
      "type": "send_message",
      "quick_reply": { "name": "Bienvenida" }
    }
    ```

    Identifica a resposta rápida por `name` (sem distinguir maiúsculas).
  </Tab>

  <Tab title="Template">
    ```jsonc theme={null}
    {
      "type": "send_message",
      "template": {
        "name": "confirmacion_cita",
        "language": "es_MX",
        "body_variables": [{ "index": 1, "value": "Ana" }]
      }
    }
    ```

    `language` é **obrigatório** (formato Meta `lower_UPPER`, ex. `es_MX`). Para
    templates com header de mídia, ver [Enviar mídia](/pt/action-groups/upload-media).
  </Tab>
</Tabs>

<Note>
  **Template com a janela fechada.** Um `send_message` de texto, mídia ou resposta rápida
  pode incluir também um `template` opcional: se na execução a [janela de
  24h](/pt/conversations) estiver **fechada**, o template é enviado no lugar do
  primário (fora da janela só é possível enviar templates); se estiver aberta,
  envia o primário. Sem `template`, um primário com a janela fechada falha com
  `WINDOW_CLOSED`.
</Note>

**Combinações válidas:**

| Combinação          | Campos                                                                                    | O que é enviado                                                      |
| ------------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| Texto               | `body`                                                                                    | O texto (requer janela aberta)                                       |
| Mídia               | `file_uuid` + `body` opcional (+ `transcription` se o arquivo não for auto-transcrevível) | A mídia com legenda (requer janela aberta)                           |
| Resposta rápida     | `quick_reply`                                                                             | A resposta rápida (requer janela aberta)                             |
| Template            | `template`                                                                                | O template (também com a janela fechada)                             |
| Primário + template | `body` \| `file_uuid` \| `quick_reply` **+** `template`                                   | O primário se a janela estiver aberta; o template se estiver fechada |

<Note>
  **Transcrição de mídia.** Quando o arquivo de uma mídia (a primária em `file_uuid` ou o
  header de um template em `template.header`) não pode ser transcrito pela visão — tipo não
  suportado ou maior que 20 MB — você deve enviar sua `transcription`. Se faltar, essa ação
  falha **por ação** durante a [execução em background](/pt/action-groups/overview#como-é-executado):
  `TRANSCRIPTION_REQUIRED` para a mídia primária, `TEMPLATE_HEADER_TRANSCRIPTION_MISSING`
  para o header do template (ambos `422`; ver [Erros](/pt/errors)).
</Note>

<CodeGroup>
  ```jsonc Texto + template theme={null}
  {
    "type": "send_message",
    "body": "Olá 👋",
    "template": {
      "name": "recordatorio",
      "language": "es_MX"
    }
  }
  ```

  ```jsonc Mídia + template theme={null}
  {
    "type": "send_message",
    "file_uuid": "7b8a1c2d-3e4f-5678-90ab-cdef12345678",
    "body": "Seu comprovante 📄",
    "template": {
      "name": "recordatorio",
      "language": "es_MX"
    }
  }
  ```

  ```jsonc Resposta rápida + template theme={null}
  {
    "type": "send_message",
    "quick_reply": { "name": "Bienvenida" },
    "template": {
      "name": "recordatorio",
      "language": "es_MX"
    }
  }
  ```
</CodeGroup>

A mídia de cada lado é independente: a do primário em `file_uuid`, a do header do
template em `template.header.file_uuid`; a de uma resposta rápida fica
configurada na própria resposta rápida. Tanto a mídia primária (`transcription`)
quanto o header do template (`template.header.transcription`) aceitam sua
transcrição — obrigatória se a visão não puder transcrever esse arquivo (ver a nota
acima).

Em uma lista, este objeto vai no array `actions` de um `POST /conversation/actions` — veja [Montar uma lista de ações](/pt/action-groups/overview#montar-uma-lista-de-ações).

## Exemplo executável

Um `send_message` em uma conversa identificada por telefone e canal. Dependendo do
que você passa, ele cobre três objetivos:

* **Mensagem ou template** — um texto ou mídia; se a [janela de 24 h](/pt/conversations) estiver fechada na execução, o template é enviado no lugar (fora da janela só é possível enviar templates).
* **Resposta rápida ou template** — igual, com uma resposta rápida salva como conteúdo principal.
* **Somente template** — apenas um template; a única forma de escrever fora da janela de 24 h. Aceita parâmetros (`body_variables`), `header` com mídia e botões (`button_parameters`).

### Request

<CodeGroup>
  ```bash Texto theme={null}
  curl -X POST "https://app.1to1ai.com/api/v1/public/{slug}/conversation/actions" \
    -H "Authorization: Bearer sk_1to1_sua_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "conversation": {
        "phone": "+525512345678",
        "channel": "ch_7A9K2M4Q"
      },
      "actions": [
        {
          "type": "send_message",
          "body": "Olá 👋, como posso te ajudar?"
        }
      ]
    }'
  ```

  ```bash Mídia theme={null}
  curl -X POST "https://app.1to1ai.com/api/v1/public/{slug}/conversation/actions" \
    -H "Authorization: Bearer sk_1to1_sua_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "conversation": {
        "phone": "+525512345678",
        "channel": "ch_7A9K2M4Q"
      },
      "actions": [
        {
          "type": "send_message",
          "file_uuid": "7b8a1c2d-3e4f-5678-90ab-cdef12345678",
          "body": "Seu comprovante 📄"
        }
      ]
    }'
  ```

  ```bash Mídia com transcrição theme={null}
  curl -X POST "https://app.1to1ai.com/api/v1/public/{slug}/conversation/actions" \
    -H "Authorization: Bearer sk_1to1_sua_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "conversation": {
        "phone": "+525512345678",
        "channel": "ch_7A9K2M4Q"
      },
      "actions": [
        {
          "type": "send_message",
          "file_uuid": "9c1b2a3d-4e5f-6789-01ab-cdef23456789",
          "body": "Seu contrato 📄",
          "transcription": "Contrato de serviço (3 páginas): plano Pro mensal, renovação automática, cancelável com 30 dias de aviso."
        }
      ]
    }'
  ```

  ```bash Resposta rápida theme={null}
  curl -X POST "https://app.1to1ai.com/api/v1/public/{slug}/conversation/actions" \
    -H "Authorization: Bearer sk_1to1_sua_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "conversation": {
        "phone": "+525512345678",
        "channel": "ch_7A9K2M4Q"
      },
      "actions": [
        {
          "type": "send_message",
          "quick_reply": { "name": "Bienvenida" }
        }
      ]
    }'
  ```

  ```bash Somente template (parâmetros, header e botão) theme={null}
  curl -X POST "https://app.1to1ai.com/api/v1/public/{slug}/conversation/actions" \
    -H "Authorization: Bearer sk_1to1_sua_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "conversation": {
        "phone": "+525512345678",
        "channel": "ch_7A9K2M4Q"
      },
      "actions": [
        {
          "type": "send_message",
          "template": {
            "name": "confirmacion_cita",
            "language": "es_MX",
            "header": {
              "type": "image",
              "file_uuid": "7b8a1c2d-3e4f-5678-90ab-cdef12345678",
              "transcription": "Flyer da consulta: consultório 3, térreo."
            },
            "body_variables": [
              { "index": 1, "value": "María" },
              { "index": 2, "value": "3 de agosto, 10:00" }
            ],
            "button_parameters": [
              { "subType": "url", "index": 0, "text": "agendamento/8f21" }
            ]
          }
        }
      ]
    }'
  ```

  ```bash Mensagem ou template theme={null}
  curl -X POST "https://app.1to1ai.com/api/v1/public/{slug}/conversation/actions" \
    -H "Authorization: Bearer sk_1to1_sua_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "conversation": {
        "phone": "+525512345678",
        "channel": "ch_7A9K2M4Q"
      },
      "actions": [
        {
          "type": "send_message",
          "file_uuid": "7b8a1c2d-3e4f-5678-90ab-cdef12345678",
          "body": "Seu comprovante 📄",
          "template": {
            "name": "recordatorio",
            "language": "es_MX",
            "header": {
              "type": "document",
              "file_uuid": "9c1b2a3d-4e5f-6789-01ab-cdef23456789",
              "transcription": "Lembrete: sua consulta é sexta-feira às 10:00 no consultório 3."
            }
          }
        }
      ]
    }'
  ```

  ```bash Resposta rápida ou template theme={null}
  curl -X POST "https://app.1to1ai.com/api/v1/public/{slug}/conversation/actions" \
    -H "Authorization: Bearer sk_1to1_sua_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "conversation": {
        "phone": "+525512345678",
        "channel": "ch_7A9K2M4Q"
      },
      "actions": [
        {
          "type": "send_message",
          "quick_reply": { "name": "Bienvenida" },
          "template": {
            "name": "recordatorio",
            "language": "es_MX"
          }
        }
      ]
    }'
  ```
</CodeGroup>

### Resposta

`202 Accepted` — o grupo foi aceito e roda em **background**. O resultado por
ação não viaja na resposta (consulte-o depois — veja [Como é executado](/pt/action-groups/overview#como-é-executado)).

```json theme={null}
{
  "status": "processing",
  "actions_accepted": 1
}
```

<ResponseField name="status" type="string">
  Sempre `processing`: confirma que o grupo foi aceito e está em execução.
</ResponseField>

<ResponseField name="actions_accepted" type="integer">
  Quantas ações do array foram **admitidas** para execução — não quantas tiveram
  sucesso.
</ResponseField>