EstadoDesarrolladoresSociosPTENESIniciar sesión
Habla con ventasEmpieza gratis
Empieza gratis
Habla con ventasEmpieza gratis
Iniciar sesiónEstadoPTENES

Referencia de la API

Multimedia

Sube imágenes, audios, vídeos y documentos a Meta y recibe un mediaId reutilizable en los envíos, o descarga la multimedia que llegó en un mensaje.

  • 3 operaciones
  • URL basehttps://api.messages.ccxcompany.co
  • AutenticaciónBearer con tu clave de API

El texto técnico de abajo viene del contrato público, openapi.json, en el idioma en que se escribió el contrato.

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

CampoDóndeTipoDescripción
numberIdobligatoriorutastring

Cuerpo de la peticiónapplication/json

CampoTipoDescripción
filenameobligatoriostring
mimeTypeobligatoriostring
dataBase64obligatoriostringBase64-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.
Ejemplo completo del cuerpo
JSON
{  "filename": "string",  "mimeType": "image/jpeg",  "dataBase64": "string"}

Respuestas

  • 201Default Response

    Campos y ejemplo de la respuesta
    CampoTipoDescripción
    mediaIdobligatoriostring
    kindobligatoriostringValores:imageaudiovideodocumentsticker
    mimeTypeobligatoriostring
    filenameobligatoriostring
    sizeobligatoriointeger
    sha256obligatoriostring
    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).

Las respuestas de error siguen el formato RFC 7807 (application/problem+json), con un código estable en el campo code. Ver los códigos de error

Ejemplo en 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"  }'
Solo los campos obligatorios. Cambia los valores de ejemplo por los tuyos.

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

CampoDóndeTipoDescripción
numberIdobligatoriorutastring
x-filenameobligatoriocabecerastring
x-content-typeobligatoriocabecerastring

Cuerpo de la peticiónapplication/octet-stream

Respuestas

  • 201Default Response

    Campos y ejemplo de la respuesta
    CampoTipoDescripción
    mediaIdobligatoriostring
    kindobligatoriostringValores:imageaudiovideodocumentsticker
    mimeTypeobligatoriostring
    filenameobligatoriostring
    sizeobligatoriointeger
    sha256obligatoriostring
    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).

Las respuestas de error siguen el formato RFC 7807 (application/problem+json), con un código estable en el campo code. Ver los códigos de error

Ejemplo en 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
Solo los campos obligatorios. Cambia los valores de ejemplo por los tuyos.

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

CampoDóndeTipoDescripción
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).
idobligatoriorutastring

Respuestas

  • 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 y ejemplo de la respuesta
    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).

Las respuestas de error siguen el formato RFC 7807 (application/problem+json), con un código estable en el campo code. Ver los códigos de error

Ejemplo en curl

cURL
curl 'https://api.messages.ccxcompany.co/messages/<id>/media' \  -H "Authorization: Bearer $CCX_API_KEY"
Solo los campos obligatorios. Cambia los valores de ejemplo por los tuyos.

Otras áreas de la API

¿Atascado en una ruta? Habla con quienes mantienen la API.

Empieza gratisHabla con ventas

Si creas la cuenta desde la web, recibes 5 US$ de crédito de prueba.