Enviar um arquivo de mídia

POST/{version}/{phone_number_id}/media

Sobe um arquivo para a Meta e devolve o id da mídia, para usar em um envio. O multipart/form-data da integração vai para a Meta como chegou, na versão da Graph API do caminho.

O header Content-Length é obrigatório (um upload em partes, sem tamanho declarado, é recusado), e a requisição inteira cabe em 16 MB.

Formatos e tamanhos da Meta, por tipo de mensagem:

- Áudio (audio): AAC, AMR, MP3, M4A ou OGG (só codec OPUS, mono). Até 16 MB. Uma mensagem de voz (voice: true) é OGG/OPUS. Tipos: audio/aac, audio/amr, audio/mpeg, audio/mp4, audio/ogg. - Documento (document): TXT, PDF, DOC/DOCX, XLS/XLSX ou PPT/PPTX. Até 100 MB na Meta — pelo upload da Synergy, até 16 MB: acima disso, envie por link. Tipos: text/plain, application/pdf, application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document, application/vnd.ms-excel, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/vnd.ms-powerpoint, application/vnd.openxmlformats-officedocument.presentationml.presentation. - Imagem (image): JPEG ou PNG, 8 bits, RGB ou RGBA. Até 5 MB. Tipos: image/jpeg, image/png. - Figurinha (sticker): WEBP de 512 × 512 px: estática até 100 KB, animada até 500 KB. Tipos: image/webp. - Vídeo (video): MP4 ou 3GPP, vídeo H.264 e áudio AAC (um só canal de áudio, ou nenhum). Até 16 MB. Tipos: video/mp4, video/3gpp.

O id vale para envios DESTE número (por 30 dias, na Meta). Use em image.id, audio.id, video.id, document.id, sticker.id ou num cabeçalho de modelo.

O que o Synergy acrescenta ou muda#

Autenticação: Authorization: Bearer <chave da Synergy> no lugar do token de acesso da Meta. A chave é conferida antes de qualquer outra coisa (formato e assinatura), precisa do escopo messages e, se for limitada a alguns números, de acesso a este. A chamada à Meta sai com o token da conta, que a integração nunca vê.
Número: {phone_number_id} precisa ser um número ativo da organização da chave; qualquer outro responde 404 (código 100), sem chegar à Meta. A versão da Graph API do caminho é repassada como veio.
Plano: sem a feature api a chamada é recusada (403, código 1390004) antes de chegar à Meta.
Limites de taxa: 2000 requisições a cada 10 s por chave × número (borda). Não contam no limite de mensagens do número.
O que a Synergy confere: multipart/form-data, o header Content-Length e o tamanho: a requisição inteira até 16 MB. Na Meta um documento vai até 100 MB; pela Synergy, acima de 16 MB envie por link no envio. O tipo do arquivo é a Meta quem valida.
O que é repassado: o formulário como chegou (boundary e campos), e a resposta da Meta como veio.

Requer#

Escopo da chave: Enviar mensagens messagesComo os escopos funcionam
Recurso do plano: API e webhooks apiVer os planos que incluem
Formato: O da API de WhatsApp Cloud da Meta, na requisição e na resposta.

Parâmetros#

No caminho#

No caminho
Nome	Tipo	Obrigatório	Descrição
version	string	obrigatório	A versão da Graph API da Meta que a chamada usa (`vN.N`): repassada à Meta como veio.
phone_number_id	string	obrigatório	O `phone_number_id` do número na Meta (o mesmo da Cloud API). Precisa ser um número ativo da organização da chave.

Cabeçalhos#

Cabeçalhos
Nome	Tipo	Obrigatório	Descrição
Authorization	string	obrigatório	Sua chave de API, no formato `Bearer <chave>`. Veja Autenticação.

Corpo#

Tipo de conteúdo: multipart/form-data.

Campos do corpo
Nome	Tipo	Obrigatório	Descrição
file	string	obrigatório	O arquivo, com o nome e o tipo MIME na parte do formulário.
type	string	opcional	O tipo MIME do arquivo: um dos que a Meta aceita (veja a descrição).
messaging_product	"whatsapp"	obrigatório

Respostas#

Respostas
Status	Código	Quando acontece
200	—	Mídia criada
400	100	O corpo não é `multipart/form-data`
400	100	Falta `Content-Length`
400	100	Acima de 16 MB
401	190	Sem `Authorization: Bearer`, chave malformada ou forjada, chave revogada, ou chave sem acesso a este número
403	200	A chave não tem o escopo `messages`
403	1390004	O plano da organização não inclui a API
404	100	O `phone_number_id` não é um número ativo desta organização (ou não tem de 5 a 20 dígitos)
429	130429	Mais de 2000 requisições em 10 s com esta chave neste número (`Retry-After: 10`)
429	130429	O número acabou de recusar por vazão, ou está sobrecarregado: o 429 se repete por 200 ms (`Retry-After: 1`)
503	2	Serviço temporariamente indisponível
Outros	131047	Erro da Meta, como ela mandou

Os erros no formato da Meta trazem o código em error.code. Ver todos os erros.

Corpo da resposta 200#

Campos da resposta 200
Nome	Tipo	Obrigatório	Descrição
id	string	obrigatório	O id da mídia, para usar em `image.id`, `document.id`… de um envio deste número.

Limites de taxa#

Borda: 2000 requisições a cada 10 s por chave × número (API_EDGE_LIMIT).

Notas#

{version} é a versão da Graph API da Meta que a integração usa (por exemplo v25.0): a chamada é repassada à Meta nessa versão. O código aceita qualquer vN.N no formato; não confere se a Meta ainda atende a versão.
Os campos do formulário (file, type, messaging_product) são os da Meta: o código não os lê, só repassa o corpo.
Dois tetos: a rota recusa Content-Length acima de 16 MB + 64 KB, e o número recusa o corpo inteiro (arquivo mais os campos do formulário) acima de 16 MB. Na prática vale o segundo.

Requisição

curl

curl -X POST 'https://api.synergyconnect.com.br/v25.0/106540352242922/media' \
  -H "Authorization: Bearer $SYNERGY_API_KEY" \
  -F 'file=@foto.jpg;type=image/jpeg' \
  -F 'type=image/jpeg' \
  -F 'messaging_product=whatsapp'

JavaScript

import { openAsBlob } from 'node:fs';

const form = new FormData();
form.append('file', await openAsBlob('foto.jpg', { type: 'image/jpeg' }), 'foto.jpg');
form.append('type', 'image/jpeg');
form.append('messaging_product', 'whatsapp');

const res = await fetch('https://api.synergyconnect.com.br/v25.0/106540352242922/media', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SYNERGY_API_KEY}`,
  },
  body: form,
});
console.log(res.status, await res.json());

Python

import os

import requests

with open("foto.jpg", "rb") as file:
    res = requests.post(
        "https://api.synergyconnect.com.br/v25.0/106540352242922/media",
        headers={
            "Authorization": f"Bearer {os.environ['SYNERGY_API_KEY']}",
        },
        files={"file": ("foto.jpg", file, "image/jpeg")},
        data={"type": "image/jpeg", "messaging_product": "whatsapp"},
    )
print(res.status_code, res.json())

Resposta

200

{
  "id": "1166846181421424"
}

400

{
  "error": {
    "message": "(#100) Invalid parameter.",
    "type": "OAuthException",
    "code": 100,
    "error_data": {
      "messaging_product": "whatsapp",
      "details": "Upload as multipart/form-data, like Meta."
    },
    "fbtrace_id": "syn-3f9a1c0b"
  }
}

Há 3 casos com este status; veja a tabela de respostas.

401

{
  "error": {
    "message": "(#190) Invalid OAuth access token.",
    "type": "OAuthException",
    "code": 190,
    "fbtrace_id": "syn-3f9a1c0b"
  }
}

403

{
  "error": {
    "message": "(#200) Permissions error: this key does not have access to this resource.",
    "type": "OAuthException",
    "code": 200,
    "fbtrace_id": "syn-3f9a1c0b"
  }
}

Há 2 casos com este status; veja a tabela de respostas.

404

{
  "error": {
    "message": "(#100) Unsupported request: object does not exist or this key cannot reach it.",
    "type": "OAuthException",
    "code": 100,
    "fbtrace_id": "syn-3f9a1c0b"
  }
}

429

{
  "error": {
    "message": "(#130429) Rate limit hit: the number's message throughput has been reached.",
    "type": "OAuthException",
    "code": 130429,
    "fbtrace_id": "syn-3f9a1c0b"
  }
}

Há 2 casos com este status; veja a tabela de respostas.

503

{
  "error": {
    "message": "(#2) Service temporarily unavailable.",
    "type": "OAuthException",
    "code": 2,
    "fbtrace_id": "syn-3f9a1c0b"
  }
}

Ficou com dúvida? Escreva para suporte@synergyconnect.com.br.