Enviar mensagens em carrossel

Use send_carousel em configuration.follow_up.actions para enviar cards com imagens no Direct do Instagram. Cada card tem um título e botões de link. Uma mensagem após os cards é uma ação separada na mesma sequência.

Campos e limites dos cards

Campo	Valor aceito
`type`	`send_carousel`.
`delay_seconds`	Inteiro obrigatório de 0 a 86399.
`cards`	De 1 a 10 cards, na ordem de exibição.
`cards[].title`	Obrigatório, de 1 a 80 valores escalares Unicode.
`cards[].subtitle`	Opcional, de 0 a 80 valores escalares Unicode.
`cards[].image_url`	URL HTTP(S) pública de imagem, obrigatória.
`cards[].buttons`	De 1 a 3 botões, na ordem de exibição.
`cards[].buttons[].type`	`url`.
`cards[].buttons[].title`	Obrigatório, de 1 a 20 valores escalares Unicode.
`cards[].buttons[].url`	URL HTTP(S) de destino, obrigatória.

Os títulos dos cards e botões não podem ter espaços em branco no início ou no fim. Os limites contam valores escalares Unicode, que podem diferir do tamanho de uma string em JavaScript. Use URLs válidas, inclusive na porta e na codificação percentual. Use o formato público cards. Propriedades desconhecidas como elements e default_action, ou um botão de card com type: "postback", são rejeitadas.

Prepare as imagens

Hospede cada imagem em uma URL que abra sem login e mantenha-a disponível até o envio. Os cards aceitam imagens. O upload pelo painel aceita arquivos JPG, PNG e GIF de até 8 MiB. REST e MCP recebem URLs e não têm operação de upload de mídia. A validação da configuração não busca a imagem nem verifica seu tamanho; salvar a configuração não comprova que o Instagram consegue acessar a mídia.

Crie uma automação completa

Este exemplo envia uma DM de abertura quando um comentário corresponde à palavra-chave. O clique no botão start_follow_up inicia a sequência do carrossel. Apenas enviar a abertura não inicia a sequência. Cliques nos links dos cards não retomam a sequência nem renovam a janela de mensagens de 24 horas. Salve este corpo completo de requisição como carousel.json. Substitua o UUID de exemplo pelo ID de uma conta acessível e cada URL de exemplo por uma URL sua. As mensagens, a palavra-chave, a pausa de cinco segundos, as respostas públicas desativadas e o intervalo entre acionamentos são escolhas ilustrativas. status: "draft" salva o exemplo para revisão.

{
  "account_id": "00000000-0000-4000-8000-000000000001",
  "name": "Collection request",
  "status": "draft",
  "configuration": {
    "contact_filter": "anyone",
    "trigger": {
      "type": "comment",
      "publication": {
        "mode": "all"
      },
      "keywords": {
        "mode": "specific",
        "match_mode": "whole_word",
        "values": [
          "CATALOG"
        ]
      }
    },
    "opening": {
      "public_reply": {
        "enabled": false
      },
      "direct_message": {
        "delay_seconds": 0,
        "message": {
          "text": "Want to see the collection?",
          "buttons": [
            {
              "type": "start_follow_up",
              "title": "Show me"
            }
          ]
        }
      }
    },
    "follow_up": {
      "actions": [
        {
          "type": "send_carousel",
          "delay_seconds": 0,
          "cards": [
            {
              "title": "Activity kit",
              "subtitle": "Creative activities for the weekend",
              "image_url": "https://example.com/activity-kit.jpg",
              "buttons": [
                {
                  "type": "url",
                  "title": "View product",
                  "url": "https://example.com/product"
                },
                {
                  "type": "url",
                  "title": "See details",
                  "url": "https://example.com/details"
                },
                {
                  "type": "url",
                  "title": "Visit store",
                  "url": "https://example.com/store"
                }
              ]
            }
          ]
        },
        {
          "type": "send_message",
          "delay_seconds": 5,
          "text": "Find more ideas in our group.",
          "buttons": [
            {
              "type": "url",
              "title": "Join the group",
              "url": "https://example.com/group"
            }
          ]
        },
        {
          "type": "finish"
        }
      ]
    },
    "extras": {
      "cooldown": {
        "mode": "none"
      }
    }
  }
}

Envie o arquivo com uma chave que tenha automations:write e acesso à conta:

curl --request POST \
  --url 'https://levios.app/api/v1/automations' \
  --header "Authorization: Bearer ${LEVIOS_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data-binary @carousel.json

Criar com status: "live" também exige automations:activate e elegibilidade da conta. Consulte Criar uma automação para ver a resposta e as regras de repetição quando o resultado da criação é incerto. Não repita automaticamente uma criação cujo resultado seja desconhecido.

Programe a mensagem seguinte

A ação send_message é separada dos botões dos cards. Seu delay_seconds é relativo à conclusão bem-sucedida da ação anterior. O exemplo programa o convite para o grupo cinco segundos após o envio bem-sucedido do carrossel. Ele não aguarda a visualização de um card, o clique em um link ou a entrada no grupo. As esperas configuradas devem caber na janela de mensagens aplicável. Pausas e novas tentativas não estendem essa janela. O espaçamento compartilhado por conta e os períodos de espera do provedor podem adiar o envio além da pausa configurada. Isso é separado dos limites de requisições da API HTTP; criar uma automação não promete envio imediato nem uma cota fixa de mensagens por hora.

Consulte, edite e trate erros

Consulte a automação após gravar e confira a ordem dos cards, os botões, a ação seguinte e o status armazenados. Ao editar, envie a configuração completa e um expected_updated_at atualizado por Atualizar uma automação. A substituição da configuração não é uma atualização parcial de um card. Siga as regras de publicação desse endpoint para automações ativas com mudanças não publicadas. Campos inválidos retornam 422 com api_automation_invalid_configuration e problemas em error.details.issues. Confira o caminho informado: cards em excesso, um quarto botão, uma URL inválida ou a ausência da pausa obrigatória precisam de correção. Preserve o restante da configuração ao corrigir um campo. Clientes que enumeram os tipos de ações de continuação precisam tratar send_carousel nas requisições e nas configurações retornadas. Consulte o documento OpenAPI atual antes de criar um decodificador que enumera todos os tipos. Para o mesmo fluxo com um agente, use Carrosséis pelo MCP.

Visão geral

Primeiros passos

Guias

Webhooks

Enviar mensagens em carrossel

Campos e limites dos cards

Prepare as imagens

Crie uma automação completa

Programe a mensagem seguinte

Consulte, edite e trate erros

​Campos e limites dos cards

​Prepare as imagens

​Crie uma automação completa

​Programe a mensagem seguinte

​Consulte, edite e trate erros

Campos e limites dos cards

Prepare as imagens

Crie uma automação completa

Programe a mensagem seguinte

Consulte, edite e trate erros