Enviar texto, imagem e arquivo

Envie um texto, uma imagem, um vídeo, um áudio ou um arquivo a um contato pela API, escolha o canal e respeite a janela de 24 horas e os limites.

Guia7 min

Atualizado em 26/10/2026

Para um aviso rápido, como "seu pedido saiu para entrega" ou a nota fiscal em PDF, não é preciso montar um fluxo: a API envia um texto ou um arquivo direto ao contato. Neste guia, você envia um texto, um arquivo e os dois juntos, e vê o que cada canal aceita.

Antes de começar

A chave de API na variável de ambiente NEXTAGS_API_KEY. Veja Autenticação com a chave de API.
O ID do contato. Veja Encontrar um contato pelo e-mail ou telefone.
Para arquivos: o arquivo num endereço público, que abra direto o arquivo, sem login e sem página no meio.
No WhatsApp: o contato dentro da janela de 24 horas. Fora dela, envie um fluxo que comece com um Modelo de Mensagem. Veja Enviar um fluxo para um contato.

Passo a passo

Passo 1: Ache o contato

Procure pelo telefone e pegue o id em data:

Procurar pelo telefone

curl "https://app.nextagsai.com.br/api/contacts/find_by_custom_field?field_id=phone&value=5511988776655" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY"

const resposta = await fetch(`https://app.nextagsai.com.br/api/contacts/find_by_custom_field?${new URLSearchParams({
  field_id: 'phone',
  value: '5511988776655',
})}`, {
  headers: {
    'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
  },
});
const dados = await resposta.json();
console.log(resposta.status, dados);

import os

import requests

resposta = requests.get(
    "https://app.nextagsai.com.br/api/contacts/find_by_custom_field",
    headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
    params={
        "field_id": "phone",
        "value": "5511988776655",
    },
    timeout=30,
)
print(resposta.status_code, resposta.json())

<?php
$ch = curl_init('https://app.nextagsai.com.br/api/contacts/find_by_custom_field?' . http_build_query([
    'field_id' => 'phone',
    'value' => '5511988776655',
]));
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
    ],
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);

O channel de cada contato diz o canal dele: 5 WhatsApp, 10 Instagram, 0 Messenger, 8 Telegram, 9 webchat e 17 TikTok.

Passo 2: Envie um texto

Use Enviar texto, com o texto em text e, se quiser, o canal em channel:

Enviar texto

curl -X POST "https://app.nextagsai.com.br/api/contacts/123456789/send/text" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Oi, Ana! Seu pedido PED-1001 saiu para entrega.",
    "channel": "whatsapp"
  }'

const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/send/text', {
  method: 'POST',
  headers: {
    'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    text: 'Oi, Ana! Seu pedido PED-1001 saiu para entrega.',
    channel: 'whatsapp',
  }),
});
const dados = await resposta.json();
console.log(resposta.status, dados);

import os

import requests

resposta = requests.post(
    "https://app.nextagsai.com.br/api/contacts/123456789/send/text",
    headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
    json={
        "text": "Oi, Ana! Seu pedido PED-1001 saiu para entrega.",
        "channel": "whatsapp",
    },
    timeout=30,
)
print(resposta.status_code, resposta.json())

<?php
$ch = curl_init('https://app.nextagsai.com.br/api/contacts/123456789/send/text');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'text' => 'Oi, Ana! Seu pedido PED-1001 saiu para entrega.',
        'channel' => 'whatsapp',
    ]),
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);

A resposta é {"success": true}. Monte o texto completo no seu sistema, com o nome e os dados do pedido já preenchidos.

O channel escolhe o canal do envio. O contrato lista estes valores:

`channel`	Texto (`send/text`)	Arquivo (`send/file`)
`whatsapp`	Sim	Sim
`instagram`	Sim	Sim
`messenger`	Sim	Sim
`telegram`	Sim	Sim
`webchat`	Sim	Não está na lista do contrato

O TikTok não aparece nessas listas. Sem channel, confira no primeiro teste por qual canal a mensagem saiu.

A janela de 24 horas

No WhatsApp, texto e arquivo só saem até 24 horas depois da última mensagem do contato. Fora dessa janela, só sai um Modelo de Mensagem aprovado, e pela API isso se faz enviando um fluxo que comece com o modelo. Veja A janela de 24 horas. No Instagram e no Messenger, a Meta dá 24 horas para mensagens automáticas; os 7 dias valem só para a resposta da equipe pela Caixa de Entrada. Veja Mensagens fora da janela no Instagram e no Messenger.

Passo 3: Envie uma imagem ou um arquivo

Use Enviar arquivo, com o endereço do arquivo em url e o tipo em type: image, video, audio ou file.

Enviar arquivo

curl -X POST "https://app.nextagsai.com.br/api/contacts/123456789/send/file" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://seusistema.exemplo.com.br/notas/PED-1001.pdf",
    "type": "file",
    "channel": "whatsapp"
  }'

const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/send/file', {
  method: 'POST',
  headers: {
    'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://seusistema.exemplo.com.br/notas/PED-1001.pdf',
    type: 'file',
    channel: 'whatsapp',
  }),
});
const dados = await resposta.json();
console.log(resposta.status, dados);

import os

import requests

resposta = requests.post(
    "https://app.nextagsai.com.br/api/contacts/123456789/send/file",
    headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
    json={
        "url": "https://seusistema.exemplo.com.br/notas/PED-1001.pdf",
        "type": "file",
        "channel": "whatsapp",
    },
    timeout=30,
)
print(resposta.status_code, resposta.json())

<?php
$ch = curl_init('https://app.nextagsai.com.br/api/contacts/123456789/send/file');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'url' => 'https://seusistema.exemplo.com.br/notas/PED-1001.pdf',
        'type' => 'file',
        'channel' => 'whatsapp',
    ]),
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);

A resposta é {"success": true}. O arquivo precisa estar no ar enquanto o envio acontece: não apague nem troque o endereço logo depois de chamar a API.

Os tipos de arquivo e os tamanhos que cada canal aceita estão em Tipos de arquivo e limites por canal. No WhatsApp, por exemplo, uma imagem vai até 5 MB e um documento até 100 MB.

Passo 4: Envie texto e arquivo juntos

Para mandar várias mensagens na ordem certa numa chamada só, use Enviar conteúdo, com as mensagens em messages:

Texto e imagem numa chamada

curl -X POST "https://app.nextagsai.com.br/api/contacts/123456789/send_content" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "message": {
          "text": "Oi, Ana! Olha como ficou o seu bolo:"
        }
      },
      {
        "message": {
          "attachment": {
            "type": "image",
            "payload": {
              "url": "https://seusistema.exemplo.com.br/img/bolo-PED-1001.jpg"
            }
          }
        }
      }
    ],
    "channel": "whatsapp"
  }'

const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/send_content', {
  method: 'POST',
  headers: {
    'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    messages: [
      {
        message: {
          text: 'Oi, Ana! Olha como ficou o seu bolo:',
        },
      },
      {
        message: {
          attachment: {
            type: 'image',
            payload: {
              url: 'https://seusistema.exemplo.com.br/img/bolo-PED-1001.jpg',
            },
          },
        },
      },
    ],
    channel: 'whatsapp',
  }),
});
const dados = await resposta.json();
console.log(resposta.status, dados);

import os

import requests

resposta = requests.post(
    "https://app.nextagsai.com.br/api/contacts/123456789/send_content",
    headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
    json={
        "messages": [
            {
                "message": {
                    "text": "Oi, Ana! Olha como ficou o seu bolo:",
                },
            },
            {
                "message": {
                    "attachment": {
                        "type": "image",
                        "payload": {
                            "url": "https://seusistema.exemplo.com.br/img/bolo-PED-1001.jpg",
                        },
                    },
                },
            },
        ],
        "channel": "whatsapp",
    },
    timeout=30,
)
print(resposta.status_code, resposta.json())

<?php
$ch = curl_init('https://app.nextagsai.com.br/api/contacts/123456789/send_content');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'messages' => [
            [
                'message' => [
                    'text' => 'Oi, Ana! Olha como ficou o seu bolo:',
                ],
            ],
            [
                'message' => [
                    'attachment' => [
                        'type' => 'image',
                        'payload' => [
                            'url' => 'https://seusistema.exemplo.com.br/img/bolo-PED-1001.jpg',
                        ],
                    ],
                ],
            ],
        ],
        'channel' => 'whatsapp',
    ]),
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);

O mesmo formato aceita botões, respostas rápidas, cartões e ações. Veja Mensagens e ações em JSON.

Pronto: como conferir

A resposta é {"success": true}.
Na Caixa de Entrada, a conversa do contato mostra o texto e o arquivo.

Se não funcionou

401 com "No valid API key provided."

A chave não chegou ou não vale. Veja Autenticação com a chave de API.

O contato não recebeu a mensagem

No WhatsApp, o contato pode estar fora da janela de 24 horas: envie um fluxo que comece com um Modelo de Mensagem. Confira também se o channel é o canal em que o contato fala com você e veja o que falhou no Registro de Erros. Veja Registro de Erros: ler e resolver.

O arquivo não chega ou chega quebrado

O endereço não abre o arquivo direto (pede login, é uma página de visualização ou redireciona) ou o arquivo passa do limite do canal. Abra o url numa janela anônima do navegador: ele precisa baixar ou mostrar o arquivo na hora. Confira também se o type combina com o arquivo. Veja Tipos de arquivo e limites por canal.

O texto chega com {{first_name}} escrito

A troca de variáveis do texto enviado pela API não foi conferida. Monte o texto completo no seu sistema antes de enviar, ou use um fluxo, que troca as variáveis. Veja Enviar um fluxo para um contato.

Faça com a IA

Copie o pedido e cole no ChatGPT ou no Claude.

Leia https://docs.nextags.com.br/guias/enviar-texto-e-arquivos.md.

Escreva, em [linguagem], uma função que envia ao contato da NexTags [o aviso, por exemplo: o código de rastreio e o PDF da nota fiscal] quando [o evento no seu sistema]. Ela procura o contato pelo telefone, envia o texto e o arquivo numa chamada só (Enviar conteúdo) e, se o contato estiver fora da janela de 24 horas do WhatsApp, envia o fluxo [ID do fluxo com o Modelo de Mensagem] no lugar. A chave vem da variável de ambiente NEXTAGS_API_KEY.

Obrigado! Sua resposta ajuda a melhorar a central.