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

Endereço: https://docs.nextags.com.br/guias/enviar-texto-e-arquivos/
Tipo: Guia

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](https://docs.nextags.com.br/comecar/autenticacao/).
- O ID do contato. Veja [Encontrar um contato pelo e-mail ou telefone](https://docs.nextags.com.br/guias/buscar-contato-por-campo/).
- 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](https://docs.nextags.com.br/guias/enviar-fluxo/).

## Passo a passo

### Passo 1: Ache o contato

Procure pelo telefone e pegue o `id` em `data`:

**Procurar pelo telefone**

```bash
curl "https://app.nextagsai.com.br/api/contacts/find_by_custom_field?field_id=phone&value=5511988776655" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY"
```
```javascript
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);
```
```python
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
<?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](https://docs.nextags.com.br/referencia/mensagens/enviar-texto/), com o texto em `text` e, se quiser, o canal em `channel`:

**Enviar texto**

```bash
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"
  }'
```
```javascript
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);
```
```python
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
<?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](https://help.nextags.com.br/tutoriais/canais/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](https://help.nextags.com.br/tutoriais/instagram-e-facebook/mensagens-fora-da-janela/).

### Passo 3: Envie uma imagem ou um arquivo

Use [Enviar arquivo](https://docs.nextags.com.br/referencia/mensagens/enviar-arquivo/), com o endereço do arquivo em `url` e o tipo em `type`: `image`, `video`, `audio` ou `file`.

**Enviar arquivo**

```bash
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"
  }'
```
```javascript
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);
```
```python
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
<?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](https://help.nextags.com.br/tutoriais/canais/tipos-de-arquivo-e-limites/). 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](https://docs.nextags.com.br/referencia/mensagens/enviar-conteudo/), com as mensagens em `messages`:

**Texto e imagem numa chamada**

```bash
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"
  }'
```
```javascript
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);
```
```python
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
<?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](https://docs.nextags.com.br/comecar/mensagens-e-acoes/).

## 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](https://docs.nextags.com.br/comecar/autenticacao/).

### 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](https://help.nextags.com.br/tutoriais/fluxos/registro-de-erros/).

### 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](https://help.nextags.com.br/tutoriais/canais/tipos-de-arquivo-e-limites/).

### 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](https://docs.nextags.com.br/guias/enviar-fluxo/).

### Faça com a IA

Cole este pedido no ChatGPT ou no Claude:

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