StatusDesenvolvedoresParceirosPTENESEntrar
Falar com vendasCriar conta grátis
Criar conta grátis
Falar com vendasCriar conta grátis
EntrarStatusPTENES

Referência da API

Mídia

Suba imagens, áudios, vídeos e documentos para a Meta e receba um mediaId reutilizável nos envios, ou baixe a mídia que chegou numa mensagem recebida.

  • 3 operações
  • URL basehttps://api.messages.ccxcompany.co
  • AutenticaçãoBearer com a sua chave de API

O texto técnico abaixo vem do contrato público, o openapi.json, no idioma em que o contrato foi escrito.

Upload a media binary to Meta and get a re-usable `mediaId`

POST/numbers/{numberId}/media

Accepts the binary as base64 to avoid bringing in a multipart parser. The route forwards the bytes to POST /{phoneNumberId}/media on the Meta Cloud API and returns the resulting mediaId (~30-day TTL).

The mediaId is then passed in the message payload: { type: "media", payload: { kind: "image", media: { id: "<mediaId>" } } }.

For files of any size, prefer POST /numbers/{numberId}/media/binary: base64 inflates the payload by 33% on the wire. This endpoint streams the decoded bytes straight to disk, so it no longer holds the file in memory — but the upload is still 33% larger to send.

Parâmetros

CampoOndeTipoDescrição
numberIdobrigatóriocaminhostring

Corpo da requisiçãoapplication/json

CampoTipoDescrição
filenameobrigatóriostring
mimeTypeobrigatóriostring
dataBase64obrigatóriostringBase64-encoded binary, capped at 140,000,000 characters (~105 MB of binary). Line breaks and whitespace inside the value are ignored, so base64 wrapped at 76 columns is accepted.
Exemplo completo do corpo
JSON
{  "filename": "string",  "mimeType": "image/jpeg",  "dataBase64": "string"}

Respostas

  • 201Default Response

    Campos e exemplo da resposta
    CampoTipoDescrição
    mediaIdobrigatóriostring
    kindobrigatóriostringValores:imageaudiovideodocumentsticker
    mimeTypeobrigatóriostring
    filenameobrigatóriostring
    sizeobrigatóriointeger
    sha256obrigatóriostring
    voiceopcionalbooleanPresent and true when the binary is OGG/Opus mono and can be sent as a WhatsApp voice note. Pass it back verbatim in payload.media.voice so the recipient's phone downloads it automatically instead of showing a manual download button.
    JSON
    {  "mediaId": "string",  "kind": "image",  "mimeType": "string",  "filename": "string",  "size": 0,  "sha256": "string",  "voice": true}

  • 400RFC 7807 problem details for BAD_REQUEST (400).

  • 401RFC 7807 problem details for UNAUTHORIZED (401).

  • 403RFC 7807 problem details for FORBIDDEN (403).

  • 404RFC 7807 problem details for NOT_FOUND (404).

  • 413RFC 7807 problem details for BAD_REQUEST (400).

  • 415RFC 7807 problem details for BAD_REQUEST (400).

  • 422RFC 7807 problem details for VALIDATION_ERROR (422).

  • 502RFC 7807 problem details for DEPENDENCY_FAILED (502).

As respostas de erro seguem o formato RFC 7807 (application/problem+json), com um código estável no campo code. Ver os códigos de erro

Exemplo em curl

cURL
curl -X POST 'https://api.messages.ccxcompany.co/numbers/<numberId>/media' \  -H "Authorization: Bearer $CCX_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "filename": "string",    "mimeType": "image/jpeg",    "dataBase64": "string"  }'
Só os campos obrigatórios. Troque os valores de exemplo pelos seus.

Upload a media binary (raw body) and get a re-usable `mediaId`

POST/numbers/{numberId}/media/binary

Igual a POST /numbers/{numberId}/media, mas o corpo é o binário CRU (application/octet-stream) em vez de base64 dentro de JSON.

Prefira este endpoint para arquivos grandes: o base64 infla 33% e obriga o servidor a materializar o conteúdo inteiro em memória.

O nome do arquivo vai em x-filename e o tipo real em x-content-type (o content-type da requisição é sempre application/octet-stream).

Parâmetros

CampoOndeTipoDescrição
numberIdobrigatóriocaminhostring
x-filenameobrigatóriocabeçalhostring
x-content-typeobrigatóriocabeçalhostring

Corpo da requisiçãoapplication/octet-stream

Respostas

  • 201Default Response

    Campos e exemplo da resposta
    CampoTipoDescrição
    mediaIdobrigatóriostring
    kindobrigatóriostringValores:imageaudiovideodocumentsticker
    mimeTypeobrigatóriostring
    filenameobrigatóriostring
    sizeobrigatóriointeger
    sha256obrigatóriostring
    voiceopcionalbooleanPresent and true when the binary is OGG/Opus mono and can be sent as a WhatsApp voice note. Pass it back verbatim in payload.media.voice so the recipient's phone downloads it automatically instead of showing a manual download button.
    JSON
    {  "mediaId": "string",  "kind": "image",  "mimeType": "string",  "filename": "string",  "size": 0,  "sha256": "string",  "voice": true}

  • 400RFC 7807 problem details for BAD_REQUEST (400).

  • 401RFC 7807 problem details for UNAUTHORIZED (401).

  • 403RFC 7807 problem details for FORBIDDEN (403).

  • 404RFC 7807 problem details for NOT_FOUND (404).

  • 413RFC 7807 problem details for BAD_REQUEST (400).

  • 415RFC 7807 problem details for BAD_REQUEST (400).

  • 422RFC 7807 problem details for VALIDATION_ERROR (422).

  • 502RFC 7807 problem details for DEPENDENCY_FAILED (502).

As respostas de erro seguem o formato RFC 7807 (application/problem+json), com um código estável no campo code. Ver os códigos de erro

Exemplo em curl

cURL
curl -X POST 'https://api.messages.ccxcompany.co/numbers/<numberId>/media/binary' \  -H "Authorization: Bearer $CCX_API_KEY" \  -H 'x-filename: <x-filename>' \  -H 'x-content-type: <x-content-type>' \  -H "Content-Type: application/octet-stream" \  --data-binary @file
Só os campos obrigatórios. Troque os valores de exemplo pelos seus.

Proxy a media binary referenced by a message

GET/messages/{id}/media

Imagem (png, jpeg, gif, webp, avif, bmp, heic, heif), PDF, áudio e vídeo abrem como estão, sem conferir a extensão do nome; qualquer outro tipo vem como application/octet-stream com Content-Disposition: attachment, e o tipo original fica em mediaStorage.mimeType.

Resolves the Meta media id from the message payload, fetches the short-lived URL from Meta, and streams the binary back to the caller. Bypasses the lookaside CDN auth requirement on the client.

With redirect=1 and a stored copy of the media, answers 302 to a pre-signed storage URL (valid for at least 1 hour, at most 2) instead of streaming — the client downloads directly from storage, with native Range support. Without redirect, the behavior is unchanged.

download=1 makes the redirected response an attachment (Content-Disposition: attachment), named after filename, else the original file name, else <messageId>.<ext>.

Any type outside that list — including what the sender declared as HTML, SVG or XML, and audio/* or video/* ending in +xml — is never served inline, streamed or redirected. A type inside the list is served normalized (image/jpg becomes image/jpeg). The original type also stays in the payload (mime_type). Streamed responses carry X-Content-Type-Options: nosniff and a restrictive Content-Security-Policy.

Parâmetros

CampoOndeTipoDescrição
redirectopcionalquerystring1 or true: answer 302 to a pre-signed storage URL when a stored copy exists.
downloadopcionalquerystring1 or true: the redirected response is served as an attachment.
filenameopcionalquerystringFile name suggested for the attachment (with download=1).
idobrigatóriocaminhostring

Respostas

  • 200A mídia. Imagem (png, jpeg, gif, webp, avif, bmp, heic, heif), PDF, áudio e vídeo saem com o tipo próprio, sem conferir a extensão do nome; qualquer outro tipo sai como application/octet-stream com Content-Disposition: attachment. O tipo original fica em mediaStorage.mimeType.

    Campos e exemplo da resposta
    JSON
    null

  • 302Redirect to a pre-signed storage URL (only with redirect=1), valid for at least 1 hour.

  • 401RFC 7807 problem details for UNAUTHORIZED (401).

  • 403RFC 7807 problem details for FORBIDDEN (403).

  • 404RFC 7807 problem details for NOT_FOUND (404).

  • 502RFC 7807 problem details for DEPENDENCY_FAILED (502).

As respostas de erro seguem o formato RFC 7807 (application/problem+json), com um código estável no campo code. Ver os códigos de erro

Exemplo em curl

cURL
curl 'https://api.messages.ccxcompany.co/messages/<id>/media' \  -H "Authorization: Bearer $CCX_API_KEY"
Só os campos obrigatórios. Troque os valores de exemplo pelos seus.

Outras áreas da API

Travou em alguma rota? Fale com quem mantém a API.

Criar conta grátisFalar com vendas

Criando a conta pelo site, você ganha R$ 10 de crédito de teste.