Consultar uma mídia

GET/{version}/{media_id}

Devolve os dados de uma mídia do número (recebida ou enviada). A url da resposta aponta para o download NESTA API, com a mesma chave: a URL da Meta expira em minutos e exige o token da conta, que a integração não tem.

Só uma mídia DESTE número é lida: qualquer outro id responde 404, sem dizer o que ele é.

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 muda: phone_number_id na query é obrigatório (na Meta é opcional), e o id é conferido como uma mídia DESTE número antes de qualquer coisa: outro id responde 404 (código 100), sem dizer o que ele é. Os campos pedidos à Meta são sempre id, url, mime_type, sha256, file_size e messaging_product.

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.
media_id	string	obrigatório	O id da mídia na Meta.

Na query#

Na query
Nome	Tipo	Obrigatório	Descrição
phone_number_id	string	obrigatório	O número dono da mídia. É o parâmetro da própria Meta, aqui obrigatório: é ele que diz de qual número é a mídia.

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.

Respostas#

Respostas
Status	Código	Quando acontece
200	—	Mídia
400	100	Falta `phone_number_id` na query
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)
404	100	O id não é uma mídia deste número
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	opcional	O id da mídia.
url	string	opcional	A URL de download NESTA API (não a da Meta): `GET /{version}/{media_id}/download?phone_number_id=…`, com a mesma chave.
mime_type	string	obrigatório	O tipo MIME do arquivo (por exemplo `image/jpeg`, `audio/ogg`, `application/pdf`).
sha256	string	obrigatório	O hash SHA-256 do arquivo, para conferir o download.
file_size	integer \| string	opcional	O tamanho em bytes.
messaging_product	"whatsapp"	opcional

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.

Requisição

curl

curl 'https://api.synergyconnect.com.br/v25.0/1166846181421424?phone_number_id=106540352242922' \
  -H "Authorization: Bearer $SYNERGY_API_KEY"

JavaScript

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

Python

import os

import requests

res = requests.get(
    "https://api.synergyconnect.com.br/v25.0/1166846181421424?phone_number_id=106540352242922",
    headers={
        "Authorization": f"Bearer {os.environ['SYNERGY_API_KEY']}",
    },
)
print(res.status_code, res.json())

Resposta

200

{
  "id": "1166846181421424",
  "url": "https://api.synergyconnect.com.br/v25.0/1166846181421424/download?phone_number_id=106540352242922",
  "mime_type": "image/jpeg",
  "sha256": "4b68ab3847feda7d6c62c1fbcbeebfa35eab7351ed5e78f4ddadea5df64b8015",
  "file_size": 303833,
  "messaging_product": "whatsapp"
}

400

{
  "error": {
    "message": "(#100) Invalid parameter.",
    "type": "OAuthException",
    "code": 100,
    "error_data": {
      "messaging_product": "whatsapp",
      "details": "The parameter \"phone_number_id\" is required."
    },
    "fbtrace_id": "syn-3f9a1c0b"
  }
}

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"
  }
}

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

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.