Subir a mídia de exemplo de um modelo

POST/v1/numbers/{phone_number_id}/templates/media

Sobe na Meta a imagem, o vídeo ou o PDF de exemplo de um cabeçalho de modelo e devolve o handle. multipart/form-data com o campo file, até 5 MB, Content-Length obrigatório. Tipos: image/jpeg, image/png, video/mp4, application/pdf.

Requer#

Escopo da chave: Gerenciar webhooks managementComo os escopos funcionam
Recurso do plano: API e webhooks apiVer os planos que incluem
Formato: Próprio do Synergy. Erros em { "error": "…" }.

Parâmetros#

No caminho#

No caminho
Nome	Tipo	Obrigatório	Descrição
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 tipo MIME na parte do formulário.

Respostas#

Respostas
Status	Código	Quando acontece
200	—	Mídia de exemplo
400	100	O corpo não é `multipart/form-data` com `file`
400	100	Falta `Content-Length`
400	100	Acima de 5 MB
400	100	Tipo de arquivo não aceito
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 `management`
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`)
429	130429	Mais de 30 escritas de modelos em 60 s com esta chave (`Retry-After: 60`)
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
handle	string	obrigatório	O identificador da mídia de exemplo na Meta: use em `example.header_handle` de um componente de cabeçalho.

Limites de taxa#

Borda: 2000 requisições a cada 10 s por chave × número (API_EDGE_LIMIT).
Escrita de modelos: 30 requisições a cada 60 s por chave (API_MGMT_LIMIT, o mesmo balde da gestão de webhooks).

Notas#

Número: {phone_number_id} precisa ser um número de WhatsApp ativo que a chave alcança; qualquer outro (inclusive o id de uma conta do Instagram) responde 404 (código 100), sem acordar o número.

Requisição

curl

curl -X POST 'https://api.synergyconnect.com.br/v1/numbers/106540352242922/templates/media' \
  -H "Authorization: Bearer $SYNERGY_API_KEY" \
  -F 'file=@exemplo.jpg;type=image/jpeg'

JavaScript

import { openAsBlob } from 'node:fs';

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

const res = await fetch('https://api.synergyconnect.com.br/v1/numbers/106540352242922/templates/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("exemplo.jpg", "rb") as file:
    res = requests.post(
        "https://api.synergyconnect.com.br/v1/numbers/106540352242922/templates/media",
        headers={
            "Authorization": f"Bearer {os.environ['SYNERGY_API_KEY']}",
        },
        files={"file": ("exemplo.jpg", file, "image/jpeg")},
    )
print(res.status_code, res.json())

Resposta

200

{
  "handle": "4::aW1hZ2UvanBlZw==:ARb3x9Qa"
}

400

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

Há 4 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á 3 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.