Enviar mensagem, resposta rápida ou template

Endpoint · POST /conversation/actions

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).

Texto
Mídia
Resposta rápida
Template

{
  "type": "send_message",
  "body": "Olá 👋"
}

Texto simples, até 4096 caracteres.

{
  "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. 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 acima do limite de tamanho que lhe corresponde); a resposta de /files/confirm antecipa isso com requires_transcription. Se faltar nesse caso, a ação falha com TRANSCRIPTION_REQUIRED.

{
  "type": "send_message",
  "quick_reply": { "name": "Bienvenida" }
}

Identifica a resposta rápida por name (sem distinguir maiúsculas).

{
  "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.

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 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.

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

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 acima do limite de tamanho que lhe corresponde — você deve enviar sua transcription. Se faltar, essa ação falha por ação durante a execução em background: TRANSCRIPTION_REQUIRED para a mídia primária, TEMPLATE_HEADER_TRANSCRIPTION_MISSING para o header do template (ambos 422; ver Erros).

Quais tipos são transcritos automaticamente pode ampliar-se por etapas. O sinal autoritativo por arquivo é requires_transcription na resposta de /files/confirm, que evita ter que acompanhar essas etapas. Os limites por trás desse sinal são de visão, distintos dos limites de upload. .doc, .ppt e .pptx não são transcritos automaticamente em nenhum tamanho.Três consequências práticas:

requires_transcription responde no momento do confirm. O gate que manda é o do envio, então um arquivo confirmado com false pode voltar a exigir transcription se a disponibilidade mudar entre o confirm e o envio. Na dúvida, envie-a.
Enviar transcription junto a um file_uuid nunca é erro, mesmo que o arquivo não precisasse: ganha sobre a transcrição automática. Sem file_uuid o body inteiro é rejeitado com INVALID_REQUEST (400), assim como uma transcription vazia ou só com espaços. Já um texto que só fica vazio ao remover os caracteres de controle passa pelo schema: o body é aceito com 202 e é essa ação que falha com INVALID_REQUEST durante a execução em background.
O limite de tamanho depende do tipo de arquivo: não é um número único para todos.

{
  "type": "send_message",
  "body": "Olá 👋",
  "template": {
    "name": "recordatorio",
    "language": "es_MX"
  }
}

{
  "type": "send_message",
  "file_uuid": "7b8a1c2d-3e4f-5678-90ab-cdef12345678",
  "body": "Seu comprovante 📄",
  "template": {
    "name": "recordatorio",
    "language": "es_MX"
  }
}

{
  "type": "send_message",
  "quick_reply": { "name": "Bienvenida" },
  "template": {
    "name": "recordatorio",
    "language": "es_MX"
  }
}

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.

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 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

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?"
      }
    ]
  }'

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 📄"
      }
    ]
  }'

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."
      }
    ]
  }'

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" }
      }
    ]
  }'

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" }
          ]
        }
      }
    ]
  }'

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."
          }
        }
      }
    ]
  }'

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"
        }
      }
    ]
  }'

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).

{
  "status": "processing",
  "actions_accepted": 1
}

string

Sempre processing: confirma que o grupo foi aceito e está em execução.

integer

Quantas ações do array foram admitidas para execução — não quantas tiveram sucesso.

Introdução

Conceitos

Guias

Ações

Enviar mensagem, resposta rápida ou template

Exemplo executável

Request

Resposta