Skip to content
Nigora Zap API

    Sign in Create account

    Sending media

    Use POST /v1/instances/{instanceId}/messages/media to send an image, video, audio or document. As with sending text, the API responds 202 and sends afterwards.

    Fields

    Section titled “Fields”
    Field Type Description
    to text, required Phone number of the recipient, with country and area code
    kind required image, video, audio or document
    url text Public address of the file, up to 2,048 characters
    base64 text File content as base64
    mimeType text File type, such as image/png. Required with base64
    fileName text, optional File name, up to 255 characters
    caption text, optional Caption, up to 1,024 characters
    quotedMessageId text, optional Message being replied to

    Provide the media through url or base64, never both and never neither. Fields that are not in the table are rejected with 400.

    By URL

    Section titled “By URL”

    The file must be at a public http or https address. The API downloads the file at send time.

    Terminal window
    curl -X POST https://api.zap.nigora.com.br/v1/instances/INSTANCIA_ID/messages/media \
      -H "Authorization: Bearer TOKEN" \
      -H "Content-Type: application/json" \
      -d '{ "to": "5511999999999", "kind": "image", "url": "https://exemplo.com/foto.jpg", "caption": "Seu comprovante" }'
    • Internal network addresses, such as localhost or private IPs, are rejected with 400 and url_not_allowed.
    • An address that is not http or https, or is malformed, is rejected with 400 and invalid_media_url.
    • The file can be up to 16 MB; for document, up to 100 MB. Above that, the message fails after being accepted, with error: "media_too_large" in the message.status webhook.
    • Without mimeType, the API uses the type reported by the file’s server.

    By base64

    Section titled “By base64”
    Terminal window
    curl -X POST https://api.zap.nigora.com.br/v1/instances/INSTANCIA_ID/messages/media \
      -H "Authorization: Bearer TOKEN" \
      -H "Content-Type: application/json" \
      -d '{ "to": "5511999999999", "kind": "document", "base64": "JVBERi0xLjQK...", "mimeType": "application/pdf", "fileName": "boleto.pdf" }'
    • The decoded file can be up to 16 MB. Above that, the response is 400 with media_too_large. For larger files, use url.
    • The whole request body can be up to 25 MB. Above that, the response is 413 with payload_too_large.
    • Invalid base64, or base64 without mimeType, returns 400 with invalid_media.

    Errors

    Section titled “Errors”
    Status Code When
    400 validation_error Field not in the table, too large or badly formatted (such as a mimeType that is not type/subtype)
    400 invalid_phone Invalid phone number
    400 invalid_media Neither url nor base64, both together, invalid base64, or base64 without mimeType
    400 invalid_media_url Malformed url, or one that does not use http/https
    400 media_too_large base64 above 16 MB
    400 url_not_allowed url points to an address that is not public
    402 instance_suspended Instance suspended or with a pending payment
    409 instance_not_connected Instance disconnected, with disableQueueWhenDisconnected on
    413 payload_too_large Body above 25 MB
    422 contact_opted_out The contact asked not to receive messages

    Failures that only show up at send time (file too large at the url, a download that did not work, a number without WhatsApp) arrive through the message.status webhook, with status: "failed". See the list of error values in Sending messages.