API reference

Channel-scoped HTTP API. Every operation under /v1 needs the channel's token as a bearer token, and opens only that channel. Errors are JSON with a stable code and a human-readable error. The product name and the origin are filled in when the document is served.

Base URL
https://api.hellohop.app/v1

The same reference as an OpenAPI 3.1 document: /docs/openapi.json

Guides and examples are in the docs.

Messages

  • POST/v1/sessions/{name}/messages/contact

    Send a contact card

    Parameters

    name (path, required)
    Channel ID.

    Request body

    to (string, required)
    display_name (string, required)
    vcard (string, required)

    Responses

    200
    OK
    400
    The request was refused as sent.
    401
    Missing, invalid or stale token, or a channel this token does not open.
    403
    The token is valid and may not do this.
    404
    The route or the named object does not exist.
    409
    The channel's state does not allow this, for example not_linked or stood_down.
    429
    A gateway flood guard or the webhook-test cooldown (rate_limited, with a Retry-After header), the gateway being busy with this channel's earlier requests (gateway_busy, Retry-After: 1), a sandbox channel's allowance (sandbox_allowance_exceeded, with Retry-After), an operator stop (daily_send_cap_exceeded), an optional warm-up protection allowance (daily_cap_<class>, only when warm-up protection is on), a history request inside its rate limit (history_request_too_soon, with Retry-After), or WhatsApp throttling the number (whatsapp_rate_limited, no Retry-After). Paid numbers have no gateway allowance. code says which: the bodies never share one.
    500
    The gateway could not complete the request.
    502
    The service behind the gateway could not be reached or answered unusably. Retry.
    503
    Temporarily unavailable, for example the token could not be checked, the gateway could not confirm its own account setup (operator_unresolved, with a Retry-After header), or a call made under a phone lane reached the lane's deadline (lane_reclaimed, with a Retry-After header and ambiguous). Unless the error explicitly says nothing was sent (for example ambiguous: false), treat any write as possibly applied; list or read the state of what you changed before retrying a write; never re-create (e.g. a group) without reading/listing first; reads can be retried after a short back-off. Honor Retry-After when present.
    504
    The outcome is unknown. Look up id in history before resending.

  • POST/v1/sessions/{name}/messages/image

    Send an image

    Parameters

    name (path, required)
    Channel ID.

    Request body

    to (string, required)
    Phone number in international form, or a JID.
    url (string, required)
    Where the gateway fetches the media.
    caption (string)
    Shown under the image.

    Responses

    200
    OK
    400
    The request was refused as sent.
    401
    Missing, invalid or stale token, or a channel this token does not open.
    403
    The token is valid and may not do this.
    404
    The route or the named object does not exist.
    409
    The channel's state does not allow this, for example not_linked or stood_down.
    413
    An uploaded file (multipart/form-data) is larger than its media type allows (media_too_large).
    429
    A gateway flood guard or the webhook-test cooldown (rate_limited, with a Retry-After header), the gateway being busy with this channel's earlier requests (gateway_busy, Retry-After: 1), a sandbox channel's allowance (sandbox_allowance_exceeded, with Retry-After), an operator stop (daily_send_cap_exceeded), an optional warm-up protection allowance (daily_cap_<class>, only when warm-up protection is on), a history request inside its rate limit (history_request_too_soon, with Retry-After), or WhatsApp throttling the number (whatsapp_rate_limited, no Retry-After). Paid numbers have no gateway allowance. code says which: the bodies never share one.
    500
    The gateway could not complete the request.
    502
    The service behind the gateway could not be reached or answered unusably. Retry.
    503
    Temporarily unavailable, for example the token could not be checked, the gateway could not confirm its own account setup (operator_unresolved, with a Retry-After header), or a call made under a phone lane reached the lane's deadline (lane_reclaimed, with a Retry-After header and ambiguous). Unless the error explicitly says nothing was sent (for example ambiguous: false), treat any write as possibly applied; list or read the state of what you changed before retrying a write; never re-create (e.g. a group) without reading/listing first; reads can be retried after a short back-off. Honor Retry-After when present.
    504
    The outcome is unknown. Look up id in history before resending.

  • POST/v1/sessions/{name}/messages/video

    Send a video

    Parameters

    name (path, required)
    Channel ID.

    Request body

    to (string, required)
    Phone number in international form, or a JID.
    url (string, required)
    Where the gateway fetches the media.
    caption (string)
    Shown under the video.

    Responses

    200
    OK
    400
    The request was refused as sent.
    401
    Missing, invalid or stale token, or a channel this token does not open.
    403
    The token is valid and may not do this.
    404
    The route or the named object does not exist.
    409
    The channel's state does not allow this, for example not_linked or stood_down.
    413
    An uploaded file (multipart/form-data) is larger than its media type allows (media_too_large).
    429
    A gateway flood guard or the webhook-test cooldown (rate_limited, with a Retry-After header), the gateway being busy with this channel's earlier requests (gateway_busy, Retry-After: 1), a sandbox channel's allowance (sandbox_allowance_exceeded, with Retry-After), an operator stop (daily_send_cap_exceeded), an optional warm-up protection allowance (daily_cap_<class>, only when warm-up protection is on), a history request inside its rate limit (history_request_too_soon, with Retry-After), or WhatsApp throttling the number (whatsapp_rate_limited, no Retry-After). Paid numbers have no gateway allowance. code says which: the bodies never share one.
    500
    The gateway could not complete the request.
    502
    The service behind the gateway could not be reached or answered unusably. Retry.
    503
    Temporarily unavailable, for example the token could not be checked, the gateway could not confirm its own account setup (operator_unresolved, with a Retry-After header), or a call made under a phone lane reached the lane's deadline (lane_reclaimed, with a Retry-After header and ambiguous). Unless the error explicitly says nothing was sent (for example ambiguous: false), treat any write as possibly applied; list or read the state of what you changed before retrying a write; never re-create (e.g. a group) without reading/listing first; reads can be retried after a short back-off. Honor Retry-After when present.
    504
    The outcome is unknown. Look up id in history before resending.

  • POST/v1/sessions/{name}/messages/audio

    Send an audio file

    Parameters

    name (path, required)
    Channel ID.

    Request body

    to (string, required)
    Phone number in international form, or a JID.
    url (string, required)
    Where the gateway fetches the media.

    Responses

    200
    OK
    400
    The request was refused as sent.
    401
    Missing, invalid or stale token, or a channel this token does not open.
    403
    The token is valid and may not do this.
    404
    The route or the named object does not exist.
    409
    The channel's state does not allow this, for example not_linked or stood_down.
    413
    An uploaded file (multipart/form-data) is larger than its media type allows (media_too_large).
    429
    A gateway flood guard or the webhook-test cooldown (rate_limited, with a Retry-After header), the gateway being busy with this channel's earlier requests (gateway_busy, Retry-After: 1), a sandbox channel's allowance (sandbox_allowance_exceeded, with Retry-After), an operator stop (daily_send_cap_exceeded), an optional warm-up protection allowance (daily_cap_<class>, only when warm-up protection is on), a history request inside its rate limit (history_request_too_soon, with Retry-After), or WhatsApp throttling the number (whatsapp_rate_limited, no Retry-After). Paid numbers have no gateway allowance. code says which: the bodies never share one.
    500
    The gateway could not complete the request.
    502
    The service behind the gateway could not be reached or answered unusably. Retry.
    503
    Temporarily unavailable, for example the token could not be checked, the gateway could not confirm its own account setup (operator_unresolved, with a Retry-After header), or a call made under a phone lane reached the lane's deadline (lane_reclaimed, with a Retry-After header and ambiguous). Unless the error explicitly says nothing was sent (for example ambiguous: false), treat any write as possibly applied; list or read the state of what you changed before retrying a write; never re-create (e.g. a group) without reading/listing first; reads can be retried after a short back-off. Honor Retry-After when present.
    504
    The outcome is unknown. Look up id in history before resending.

  • POST/v1/sessions/{name}/messages/voice

    Send a voice note

    Parameters

    name (path, required)
    Channel ID.

    Request body

    to (string, required)
    Phone number in international form, or a JID.
    url (string, required)
    Where the gateway fetches the media.

    Responses

    200
    OK
    400
    The request was refused as sent.
    401
    Missing, invalid or stale token, or a channel this token does not open.
    403
    The token is valid and may not do this.
    404
    The route or the named object does not exist.
    409
    The channel's state does not allow this, for example not_linked or stood_down.
    413
    An uploaded file (multipart/form-data) is larger than its media type allows (media_too_large).
    429
    A gateway flood guard or the webhook-test cooldown (rate_limited, with a Retry-After header), the gateway being busy with this channel's earlier requests (gateway_busy, Retry-After: 1), a sandbox channel's allowance (sandbox_allowance_exceeded, with Retry-After), an operator stop (daily_send_cap_exceeded), an optional warm-up protection allowance (daily_cap_<class>, only when warm-up protection is on), a history request inside its rate limit (history_request_too_soon, with Retry-After), or WhatsApp throttling the number (whatsapp_rate_limited, no Retry-After). Paid numbers have no gateway allowance. code says which: the bodies never share one.
    500
    The gateway could not complete the request.
    502
    The service behind the gateway could not be reached or answered unusably. Retry.
    503
    Temporarily unavailable, for example the token could not be checked, the gateway could not confirm its own account setup (operator_unresolved, with a Retry-After header), or a call made under a phone lane reached the lane's deadline (lane_reclaimed, with a Retry-After header and ambiguous). Unless the error explicitly says nothing was sent (for example ambiguous: false), treat any write as possibly applied; list or read the state of what you changed before retrying a write; never re-create (e.g. a group) without reading/listing first; reads can be retried after a short back-off. Honor Retry-After when present.
    504
    The outcome is unknown. Look up id in history before resending.

  • POST/v1/sessions/{name}/messages/document

    Send a document

    Parameters

    name (path, required)
    Channel ID.

    Request body

    to (string, required)
    Phone number in international form, or a JID.
    url (string, required)
    Where the gateway fetches the media.
    caption (string)
    Shown under the document.
    filename (string)
    The name the recipient sees. Defaults to the URL's last path segment, then document plus an extension for its type.
    mime_type (string)
    The document's media type, e.g. application/pdf.

    Responses

    200
    OK
    400
    The request was refused as sent.
    401
    Missing, invalid or stale token, or a channel this token does not open.
    403
    The token is valid and may not do this.
    404
    The route or the named object does not exist.
    409
    The channel's state does not allow this, for example not_linked or stood_down.
    413
    An uploaded file (multipart/form-data) is larger than its media type allows (media_too_large).
    429
    A gateway flood guard or the webhook-test cooldown (rate_limited, with a Retry-After header), the gateway being busy with this channel's earlier requests (gateway_busy, Retry-After: 1), a sandbox channel's allowance (sandbox_allowance_exceeded, with Retry-After), an operator stop (daily_send_cap_exceeded), an optional warm-up protection allowance (daily_cap_<class>, only when warm-up protection is on), a history request inside its rate limit (history_request_too_soon, with Retry-After), or WhatsApp throttling the number (whatsapp_rate_limited, no Retry-After). Paid numbers have no gateway allowance. code says which: the bodies never share one.
    500
    The gateway could not complete the request.
    502
    The service behind the gateway could not be reached or answered unusably. Retry.
    503
    Temporarily unavailable, for example the token could not be checked, the gateway could not confirm its own account setup (operator_unresolved, with a Retry-After header), or a call made under a phone lane reached the lane's deadline (lane_reclaimed, with a Retry-After header and ambiguous). Unless the error explicitly says nothing was sent (for example ambiguous: false), treat any write as possibly applied; list or read the state of what you changed before retrying a write; never re-create (e.g. a group) without reading/listing first; reads can be retried after a short back-off. Honor Retry-After when present.
    504
    The outcome is unknown. Look up id in history before resending.

  • POST/v1/sessions/{name}/messages/poll

    Send a poll

    Parameters

    name (path, required)
    Channel ID.

    Request body

    to (string, required)
    Phone number in international form, or a JID.
    question (string, required)
    The question.
    options (array of string, required)
    The options, each different.
    multiple (boolean)
    Let a voter choose more than one option. Default false.

    Responses

    200
    OK
    400
    The request was refused as sent.
    401
    Missing, invalid or stale token, or a channel this token does not open.
    403
    The token is valid and may not do this.
    404
    The route or the named object does not exist.
    409
    The channel's state does not allow this, for example not_linked or stood_down.
    429
    A gateway flood guard or the webhook-test cooldown (rate_limited, with a Retry-After header), the gateway being busy with this channel's earlier requests (gateway_busy, Retry-After: 1), a sandbox channel's allowance (sandbox_allowance_exceeded, with Retry-After), an operator stop (daily_send_cap_exceeded), an optional warm-up protection allowance (daily_cap_<class>, only when warm-up protection is on), a history request inside its rate limit (history_request_too_soon, with Retry-After), or WhatsApp throttling the number (whatsapp_rate_limited, no Retry-After). Paid numbers have no gateway allowance. code says which: the bodies never share one.
    500
    The gateway could not complete the request.
    502
    The service behind the gateway could not be reached or answered unusably. Retry.
    503
    Temporarily unavailable, for example the token could not be checked, the gateway could not confirm its own account setup (operator_unresolved, with a Retry-After header), or a call made under a phone lane reached the lane's deadline (lane_reclaimed, with a Retry-After header and ambiguous). Unless the error explicitly says nothing was sent (for example ambiguous: false), treat any write as possibly applied; list or read the state of what you changed before retrying a write; never re-create (e.g. a group) without reading/listing first; reads can be retried after a short back-off. Honor Retry-After when present.
    504
    The outcome is unknown. Look up id in history before resending.

  • DELETE/v1/sessions/{name}/messages/{message}

    Delete a message for everyone

    Parameters

    name (path, required)
    Channel ID.
    message (path, required)
    ID of a message this channel has in its message log (sent or received while connected).

    Responses

    200
    OK
    400
    The request was refused as sent.
    401
    Missing, invalid or stale token, or a channel this token does not open.
    403
    The token is valid and may not do this.
    404
    The route or the named object does not exist.
    409
    The channel's state does not allow this, for example not_linked or stood_down.
    429
    A gateway flood guard or the webhook-test cooldown (rate_limited, with a Retry-After header), the gateway being busy with this channel's earlier requests (gateway_busy, Retry-After: 1), a sandbox channel's allowance (sandbox_allowance_exceeded, with Retry-After), an operator stop (daily_send_cap_exceeded), an optional warm-up protection allowance (daily_cap_<class>, only when warm-up protection is on), a history request inside its rate limit (history_request_too_soon, with Retry-After), or WhatsApp throttling the number (whatsapp_rate_limited, no Retry-After). Paid numbers have no gateway allowance. code says which: the bodies never share one.
    500
    The gateway could not complete the request.
    502
    The service behind the gateway could not be reached or answered unusably. Retry.
    503
    Temporarily unavailable, for example the token could not be checked, the gateway could not confirm its own account setup (operator_unresolved, with a Retry-After header), or a call made under a phone lane reached the lane's deadline (lane_reclaimed, with a Retry-After header and ambiguous). Unless the error explicitly says nothing was sent (for example ambiguous: false), treat any write as possibly applied; list or read the state of what you changed before retrying a write; never re-create (e.g. a group) without reading/listing first; reads can be retried after a short back-off. Honor Retry-After when present.
    504
    The outcome is unknown. Look up id in history before resending.

  • PUT/v1/sessions/{name}/messages/{message}/reaction

    React to a message

    Parameters

    name (path, required)
    Channel ID.
    message (path, required)
    ID of a message this channel has in its message log (sent or received while connected).

    Request body

    emoji (string, required)
    One emoji.

    Responses

    200
    OK
    400
    The request was refused as sent.
    401
    Missing, invalid or stale token, or a channel this token does not open.
    403
    The token is valid and may not do this.
    404
    The route or the named object does not exist.
    409
    The channel's state does not allow this, for example not_linked or stood_down.
    429
    A gateway flood guard or the webhook-test cooldown (rate_limited, with a Retry-After header), the gateway being busy with this channel's earlier requests (gateway_busy, Retry-After: 1), a sandbox channel's allowance (sandbox_allowance_exceeded, with Retry-After), an operator stop (daily_send_cap_exceeded), an optional warm-up protection allowance (daily_cap_<class>, only when warm-up protection is on), a history request inside its rate limit (history_request_too_soon, with Retry-After), or WhatsApp throttling the number (whatsapp_rate_limited, no Retry-After). Paid numbers have no gateway allowance. code says which: the bodies never share one.
    500
    The gateway could not complete the request.
    502
    The service behind the gateway could not be reached or answered unusably. Retry.
    503
    Temporarily unavailable, for example the token could not be checked, the gateway could not confirm its own account setup (operator_unresolved, with a Retry-After header), or a call made under a phone lane reached the lane's deadline (lane_reclaimed, with a Retry-After header and ambiguous). Unless the error explicitly says nothing was sent (for example ambiguous: false), treat any write as possibly applied; list or read the state of what you changed before retrying a write; never re-create (e.g. a group) without reading/listing first; reads can be retried after a short back-off. Honor Retry-After when present.
    504
    The outcome is unknown. Look up id in history before resending.

  • DELETE/v1/sessions/{name}/messages/{message}/reaction

    Remove a reaction

    Parameters

    name (path, required)
    Channel ID.
    message (path, required)
    ID of a message this channel has in its message log (sent or received while connected).

    Responses

    200
    OK
    400
    The request was refused as sent.
    401
    Missing, invalid or stale token, or a channel this token does not open.
    403
    The token is valid and may not do this.
    404
    The route or the named object does not exist.
    409
    The channel's state does not allow this, for example not_linked or stood_down.
    429
    A gateway flood guard or the webhook-test cooldown (rate_limited, with a Retry-After header), the gateway being busy with this channel's earlier requests (gateway_busy, Retry-After: 1), a sandbox channel's allowance (sandbox_allowance_exceeded, with Retry-After), an operator stop (daily_send_cap_exceeded), an optional warm-up protection allowance (daily_cap_<class>, only when warm-up protection is on), a history request inside its rate limit (history_request_too_soon, with Retry-After), or WhatsApp throttling the number (whatsapp_rate_limited, no Retry-After). Paid numbers have no gateway allowance. code says which: the bodies never share one.
    500
    The gateway could not complete the request.
    502
    The service behind the gateway could not be reached or answered unusably. Retry.
    503
    Temporarily unavailable, for example the token could not be checked, the gateway could not confirm its own account setup (operator_unresolved, with a Retry-After header), or a call made under a phone lane reached the lane's deadline (lane_reclaimed, with a Retry-After header and ambiguous). Unless the error explicitly says nothing was sent (for example ambiguous: false), treat any write as possibly applied; list or read the state of what you changed before retrying a write; never re-create (e.g. a group) without reading/listing first; reads can be retried after a short back-off. Honor Retry-After when present.
    504
    The outcome is unknown. Look up id in history before resending.

  • POST/v1/sessions/{name}/messages/read

    Send read receipts

    Parameters

    name (path, required)
    Channel ID.

    Request body

    chat (string)
    sender (string)
    message_ids (array of string)
    up_to (boolean)
    Only with message_ids. When true, every unread message in the chat at or before the newest id you pass is also marked read, each to its own sender in a group, so everyone you have read up to sees it. receipted then counts those messages too; an id you pass that is already read is not marked again. Without it (the default) only the ids you pass are marked. When the unread range holds more than 5 senders or 500 messages, only the oldest unread messages are marked (at most 5 senders and 500 messages per request), the answer carries partial: true, and the rest stays unread: send the same request again to continue. partial is absent when everything was marked. A request that fails after a receipt went out is never a 4xx: it is 502 receipt_partial with receipted, the count already marked.

    Responses

    200
    OK
    400
    The request was refused as sent.
    401
    Missing, invalid or stale token, or a channel this token does not open.
    403
    The token is valid and may not do this.
    404
    The route or the named object does not exist.
    409
    The channel's state does not allow this, for example not_linked or stood_down.
    429
    A gateway flood guard or the webhook-test cooldown (rate_limited, with a Retry-After header), the gateway being busy with this channel's earlier requests (gateway_busy, Retry-After: 1), a sandbox channel's allowance (sandbox_allowance_exceeded, with Retry-After), an operator stop (daily_send_cap_exceeded), an optional warm-up protection allowance (daily_cap_<class>, only when warm-up protection is on), a history request inside its rate limit (history_request_too_soon, with Retry-After), or WhatsApp throttling the number (whatsapp_rate_limited, no Retry-After). Paid numbers have no gateway allowance. code says which: the bodies never share one.
    500
    The gateway could not complete the request.
    502
    Either the service behind the gateway could not be reached (retry), or, with code receipt_partial, some read receipts went out before the request failed: receipted is how many messages were marked. Do not resend a receipt_partial request as is.
    503
    Temporarily unavailable, for example the token could not be checked, the gateway could not confirm its own account setup (operator_unresolved, with a Retry-After header), or a call made under a phone lane reached the lane's deadline (lane_reclaimed, with a Retry-After header and ambiguous). Unless the error explicitly says nothing was sent (for example ambiguous: false), treat any write as possibly applied; list or read the state of what you changed before retrying a write; never re-create (e.g. a group) without reading/listing first; reads can be retried after a short back-off. Honor Retry-After when present.

  • POST/v1/sessions/{name}/messages/text

    Send a text

    Parameters

    name (path, required)
    Channel ID.

    Request body

    to (string, required)
    Phone number in international form, or a JID.
    text (string, required)
    The message.
    mentions (array of string)
    Phone numbers or JIDs to mention.
    quoted (string)
    ID of a message in the same chat to reply to.

    Responses

    200
    OK
    400
    The request was refused as sent.
    401
    Missing, invalid or stale token, or a channel this token does not open.
    403
    The token is valid and may not do this.
    404
    The route or the named object does not exist.
    409
    The channel's state does not allow this, for example not_linked or stood_down.
    429
    A gateway flood guard or the webhook-test cooldown (rate_limited, with a Retry-After header), the gateway being busy with this channel's earlier requests (gateway_busy, Retry-After: 1), a sandbox channel's allowance (sandbox_allowance_exceeded, with Retry-After), an operator stop (daily_send_cap_exceeded), an optional warm-up protection allowance (daily_cap_<class>, only when warm-up protection is on), a history request inside its rate limit (history_request_too_soon, with Retry-After), or WhatsApp throttling the number (whatsapp_rate_limited, no Retry-After). Paid numbers have no gateway allowance. code says which: the bodies never share one.
    500
    The gateway could not complete the request.
    502
    The service behind the gateway could not be reached or answered unusably. Retry.
    503
    Temporarily unavailable, for example the token could not be checked, the gateway could not confirm its own account setup (operator_unresolved, with a Retry-After header), or a call made under a phone lane reached the lane's deadline (lane_reclaimed, with a Retry-After header and ambiguous). Unless the error explicitly says nothing was sent (for example ambiguous: false), treat any write as possibly applied; list or read the state of what you changed before retrying a write; never re-create (e.g. a group) without reading/listing first; reads can be retried after a short back-off. Honor Retry-After when present.
    504
    The outcome is unknown. Look up id in history before resending.

  • POST/v1/sessions/{name}/presence

    Set presence

    Parameters

    name (path, required)
    Channel ID.

    Request body

    presence (string, required)

    Responses

    200
    OK
    400
    The request was refused as sent.
    401
    Missing, invalid or stale token, or a channel this token does not open.
    403
    The token is valid and may not do this.
    404
    The route or the named object does not exist.
    409
    The channel's state does not allow this, for example not_linked or stood_down.
    429
    A gateway flood guard or the webhook-test cooldown (rate_limited, with a Retry-After header), the gateway being busy with this channel's earlier requests (gateway_busy, Retry-After: 1), a sandbox channel's allowance (sandbox_allowance_exceeded, with Retry-After), an operator stop (daily_send_cap_exceeded), an optional warm-up protection allowance (daily_cap_<class>, only when warm-up protection is on), a history request inside its rate limit (history_request_too_soon, with Retry-After), or WhatsApp throttling the number (whatsapp_rate_limited, no Retry-After). Paid numbers have no gateway allowance. code says which: the bodies never share one.
    500
    The gateway could not complete the request.
    502
    The service behind the gateway could not be reached or answered unusably. Retry.
    503
    Temporarily unavailable, for example the token could not be checked, the gateway could not confirm its own account setup (operator_unresolved, with a Retry-After header), or a call made under a phone lane reached the lane's deadline (lane_reclaimed, with a Retry-After header and ambiguous). Unless the error explicitly says nothing was sent (for example ambiguous: false), treat any write as possibly applied; list or read the state of what you changed before retrying a write; never re-create (e.g. a group) without reading/listing first; reads can be retried after a short back-off. Honor Retry-After when present.

  • POST/v1/sessions/{name}/typing

    Show or clear the typing indicator

    Parameters

    name (path, required)
    Channel ID.

    Request body

    chat (string, required)
    state (string, required)

    Responses

    200
    OK
    400
    The request was refused as sent.
    401
    Missing, invalid or stale token, or a channel this token does not open.
    403
    The token is valid and may not do this.
    404
    The route or the named object does not exist.
    409
    The channel's state does not allow this, for example not_linked or stood_down.
    429
    A gateway flood guard or the webhook-test cooldown (rate_limited, with a Retry-After header), the gateway being busy with this channel's earlier requests (gateway_busy, Retry-After: 1), a sandbox channel's allowance (sandbox_allowance_exceeded, with Retry-After), an operator stop (daily_send_cap_exceeded), an optional warm-up protection allowance (daily_cap_<class>, only when warm-up protection is on), a history request inside its rate limit (history_request_too_soon, with Retry-After), or WhatsApp throttling the number (whatsapp_rate_limited, no Retry-After). Paid numbers have no gateway allowance. code says which: the bodies never share one.
    500
    The gateway could not complete the request.
    502
    The service behind the gateway could not be reached or answered unusably. Retry.
    503
    Temporarily unavailable, for example the token could not be checked, the gateway could not confirm its own account setup (operator_unresolved, with a Retry-After header), or a call made under a phone lane reached the lane's deadline (lane_reclaimed, with a Retry-After header and ambiguous). Unless the error explicitly says nothing was sent (for example ambiguous: false), treat any write as possibly applied; list or read the state of what you changed before retrying a write; never re-create (e.g. a group) without reading/listing first; reads can be retried after a short back-off. Honor Retry-After when present.

Chats

  • GET/v1/sessions/{name}/history-sync

    Read whether this channel stores synced history

    Parameters

    name (path, required)
    Channel ID.

    Responses

    200
    OK
    400
    The request was refused as sent.
    401
    Missing, invalid or stale token, or a channel this token does not open.
    403
    The token is valid and may not do this.
    404
    The route or the named object does not exist.
    429
    A gateway flood guard or the webhook-test cooldown (rate_limited, with a Retry-After header), the gateway being busy with this channel's earlier requests (gateway_busy, Retry-After: 1), a sandbox channel's allowance (sandbox_allowance_exceeded, with Retry-After), an operator stop (daily_send_cap_exceeded), an optional warm-up protection allowance (daily_cap_<class>, only when warm-up protection is on), a history request inside its rate limit (history_request_too_soon, with Retry-After), or WhatsApp throttling the number (whatsapp_rate_limited, no Retry-After). Paid numbers have no gateway allowance. code says which: the bodies never share one.
    500
    The gateway could not complete the request.
    502
    The service behind the gateway could not be reached or answered unusably. Retry.
    503
    Temporarily unavailable, for example the token could not be checked, the gateway could not confirm its own account setup (operator_unresolved, with a Retry-After header), or a call made under a phone lane reached the lane's deadline (lane_reclaimed, with a Retry-After header and ambiguous). Unless the error explicitly says nothing was sent (for example ambiguous: false), treat any write as possibly applied; list or read the state of what you changed before retrying a write; never re-create (e.g. a group) without reading/listing first; reads can be retried after a short back-off. Honor Retry-After when present.

  • PUT/v1/sessions/{name}/history-sync

    Turn storing synced history on or off for this channel

    Parameters

    name (path, required)
    Channel ID.

    Request body

    store_history_sync (boolean, required)

    Responses

    200
    OK
    400
    The request was refused as sent.
    401
    Missing, invalid or stale token, or a channel this token does not open.
    403
    The token is valid and may not do this.
    404
    The route or the named object does not exist.
    429
    A gateway flood guard or the webhook-test cooldown (rate_limited, with a Retry-After header), the gateway being busy with this channel's earlier requests (gateway_busy, Retry-After: 1), a sandbox channel's allowance (sandbox_allowance_exceeded, with Retry-After), an operator stop (daily_send_cap_exceeded), an optional warm-up protection allowance (daily_cap_<class>, only when warm-up protection is on), a history request inside its rate limit (history_request_too_soon, with Retry-After), or WhatsApp throttling the number (whatsapp_rate_limited, no Retry-After). Paid numbers have no gateway allowance. code says which: the bodies never share one.
    500
    The gateway could not complete the request.
    502
    The service behind the gateway could not be reached or answered unusably. Retry.
    503
    Temporarily unavailable, for example the token could not be checked, the gateway could not confirm its own account setup (operator_unresolved, with a Retry-After header), or a call made under a phone lane reached the lane's deadline (lane_reclaimed, with a Retry-After header and ambiguous). Unless the error explicitly says nothing was sent (for example ambiguous: false), treat any write as possibly applied; list or read the state of what you changed before retrying a write; never re-create (e.g. a group) without reading/listing first; reads can be retried after a short back-off. Honor Retry-After when present.

  • POST/v1/sessions/{name}/chats/{chat}/history-requests

    Ask the paired phone for older messages of one chat

    Parameters

    name (path, required)
    Channel ID.
    chat (path, required)
    Chat JID.

    Request body

    count (integer)
    How many older messages to ask for.

    Responses

    202
    Requested
    400
    The request was refused as sent.
    401
    Missing, invalid or stale token, or a channel this token does not open.
    403
    The token is valid and may not do this.
    404
    The route or the named object does not exist.
    409
    The channel's state does not allow this, for example not_linked or stood_down.
    429
    A gateway flood guard or the webhook-test cooldown (rate_limited, with a Retry-After header), the gateway being busy with this channel's earlier requests (gateway_busy, Retry-After: 1), a sandbox channel's allowance (sandbox_allowance_exceeded, with Retry-After), an operator stop (daily_send_cap_exceeded), an optional warm-up protection allowance (daily_cap_<class>, only when warm-up protection is on), a history request inside its rate limit (history_request_too_soon, with Retry-After), or WhatsApp throttling the number (whatsapp_rate_limited, no Retry-After). Paid numbers have no gateway allowance. code says which: the bodies never share one.
    500
    The gateway could not complete the request.
    502
    The service behind the gateway could not be reached or answered unusably. Retry.
    503
    Temporarily unavailable, for example the token could not be checked, the gateway could not confirm its own account setup (operator_unresolved, with a Retry-After header), or a call made under a phone lane reached the lane's deadline (lane_reclaimed, with a Retry-After header and ambiguous). Unless the error explicitly says nothing was sent (for example ambiguous: false), treat any write as possibly applied; list or read the state of what you changed before retrying a write; never re-create (e.g. a group) without reading/listing first; reads can be retried after a short back-off. Honor Retry-After when present.

  • GET/v1/sessions/{name}/chats

    List chats, up to 100

    Parameters

    name (path, required)
    Channel ID.

    Responses

    200
    OK
    400
    The request was refused as sent.
    401
    Missing, invalid or stale token, or a channel this token does not open.
    404
    The route or the named object does not exist.
    429
    A gateway flood guard or the webhook-test cooldown (rate_limited, with a Retry-After header), the gateway being busy with this channel's earlier requests (gateway_busy, Retry-After: 1), a sandbox channel's allowance (sandbox_allowance_exceeded, with Retry-After), an operator stop (daily_send_cap_exceeded), an optional warm-up protection allowance (daily_cap_<class>, only when warm-up protection is on), a history request inside its rate limit (history_request_too_soon, with Retry-After), or WhatsApp throttling the number (whatsapp_rate_limited, no Retry-After). Paid numbers have no gateway allowance. code says which: the bodies never share one.
    500
    The gateway could not complete the request.
    502
    The service behind the gateway could not be reached or answered unusably. Retry.
    503
    Temporarily unavailable, for example the token could not be checked, the gateway could not confirm its own account setup (operator_unresolved, with a Retry-After header), or a call made under a phone lane reached the lane's deadline (lane_reclaimed, with a Retry-After header and ambiguous). Unless the error explicitly says nothing was sent (for example ambiguous: false), treat any write as possibly applied; list or read the state of what you changed before retrying a write; never re-create (e.g. a group) without reading/listing first; reads can be retried after a short back-off. Honor Retry-After when present.

  • GET/v1/sessions/{name}/chats/{chat}/messages

    Read a conversation (a person or a group), newest first, one page at a time

    Parameters

    name (path, required)
    Channel ID.
    chat (path, required)
    Chat JID.
    limit (query)
    Messages per page, 1 to 500. Default 50.
    before (query)
    Continue from a previous page: its next_before, exactly as returned. Any other value is a 400.

    Responses

    200
    OK
    400
    The request was refused as sent.
    401
    Missing, invalid or stale token, or a channel this token does not open.
    403
    The token is valid and may not do this.
    404
    The route or the named object does not exist.
    429
    A gateway flood guard or the webhook-test cooldown (rate_limited, with a Retry-After header), the gateway being busy with this channel's earlier requests (gateway_busy, Retry-After: 1), a sandbox channel's allowance (sandbox_allowance_exceeded, with Retry-After), an operator stop (daily_send_cap_exceeded), an optional warm-up protection allowance (daily_cap_<class>, only when warm-up protection is on), a history request inside its rate limit (history_request_too_soon, with Retry-After), or WhatsApp throttling the number (whatsapp_rate_limited, no Retry-After). Paid numbers have no gateway allowance. code says which: the bodies never share one.
    500
    The gateway could not complete the request.
    502
    The service behind the gateway could not be reached or answered unusably. Retry.
    503
    Temporarily unavailable, for example the token could not be checked, the gateway could not confirm its own account setup (operator_unresolved, with a Retry-After header), or a call made under a phone lane reached the lane's deadline (lane_reclaimed, with a Retry-After header and ambiguous). Unless the error explicitly says nothing was sent (for example ambiguous: false), treat any write as possibly applied; list or read the state of what you changed before retrying a write; never re-create (e.g. a group) without reading/listing first; reads can be retried after a short back-off. Honor Retry-After when present.

  • GET/v1/sessions/{name}/media/{id}

    Download media by ID

    Parameters

    name (path, required)
    Channel ID.
    id (path, required)
    Media ID, as delivered in a message's media_id.

    Responses

    200
    The media bytes. Always served as application/octet-stream, as an attachment.
    400
    The request was refused as sent.
    401
    Missing, invalid or stale token, or a channel this token does not open.
    403
    One answer for media that belongs to another channel, to nobody, or does not exist (media_forbidden).
    404
    The route or the named object does not exist.
    429
    A gateway flood guard or the webhook-test cooldown (rate_limited, with a Retry-After header), the gateway being busy with this channel's earlier requests (gateway_busy, Retry-After: 1), a sandbox channel's allowance (sandbox_allowance_exceeded, with Retry-After), an operator stop (daily_send_cap_exceeded), an optional warm-up protection allowance (daily_cap_<class>, only when warm-up protection is on), a history request inside its rate limit (history_request_too_soon, with Retry-After), or WhatsApp throttling the number (whatsapp_rate_limited, no Retry-After). Paid numbers have no gateway allowance. code says which: the bodies never share one.
    500
    The gateway could not complete the request.
    502
    The service behind the gateway could not be reached or answered unusably. Retry.
    503
    Temporarily unavailable, for example the token could not be checked, the gateway could not confirm its own account setup (operator_unresolved, with a Retry-After header), or a call made under a phone lane reached the lane's deadline (lane_reclaimed, with a Retry-After header and ambiguous). Unless the error explicitly says nothing was sent (for example ambiguous: false), treat any write as possibly applied; list or read the state of what you changed before retrying a write; never re-create (e.g. a group) without reading/listing first; reads can be retried after a short back-off. Honor Retry-After when present.

Groups

  • GET/v1/sessions/{name}/groups

    List groups

    Parameters

    name (path, required)
    Channel ID.

    Responses

    200
    OK
    400
    The request was refused as sent.
    401
    Missing, invalid or stale token, or a channel this token does not open.
    403
    The token is valid and may not do this.
    404
    The route or the named object does not exist.
    409
    The channel's state does not allow this, for example not_linked or stood_down.
    429
    A gateway flood guard or the webhook-test cooldown (rate_limited, with a Retry-After header), the gateway being busy with this channel's earlier requests (gateway_busy, Retry-After: 1), a sandbox channel's allowance (sandbox_allowance_exceeded, with Retry-After), an operator stop (daily_send_cap_exceeded), an optional warm-up protection allowance (daily_cap_<class>, only when warm-up protection is on), a history request inside its rate limit (history_request_too_soon, with Retry-After), or WhatsApp throttling the number (whatsapp_rate_limited, no Retry-After). Paid numbers have no gateway allowance. code says which: the bodies never share one.
    500
    The gateway could not complete the request.
    502
    The service behind the gateway could not be reached or answered unusably. Retry.
    503
    Temporarily unavailable, for example the token could not be checked, the gateway could not confirm its own account setup (operator_unresolved, with a Retry-After header), or a call made under a phone lane reached the lane's deadline (lane_reclaimed, with a Retry-After header and ambiguous). Unless the error explicitly says nothing was sent (for example ambiguous: false), treat any write as possibly applied; list or read the state of what you changed before retrying a write; never re-create (e.g. a group) without reading/listing first; reads can be retried after a short back-off. Honor Retry-After when present.

  • POST/v1/sessions/{name}/groups

    Create a group

    Parameters

    name (path, required)
    Channel ID.

    Request body

    subject (string, required)
    participants (array of string)
    parent_jid (string)
    Create the group inside this community.

    Responses

    201
    Created
    400
    The request was refused as sent.
    401
    Missing, invalid or stale token, or a channel this token does not open.
    403
    The token is valid and may not do this.
    404
    The route or the named object does not exist.
    409
    The channel's state does not allow this, for example not_linked or stood_down.
    429
    A gateway flood guard or the webhook-test cooldown (rate_limited, with a Retry-After header), the gateway being busy with this channel's earlier requests (gateway_busy, Retry-After: 1), a sandbox channel's allowance (sandbox_allowance_exceeded, with Retry-After), an operator stop (daily_send_cap_exceeded), an optional warm-up protection allowance (daily_cap_<class>, only when warm-up protection is on), a history request inside its rate limit (history_request_too_soon, with Retry-After), or WhatsApp throttling the number (whatsapp_rate_limited, no Retry-After). Paid numbers have no gateway allowance. code says which: the bodies never share one.
    500
    The gateway could not complete the request.
    502
    The service behind the gateway could not be reached or answered unusably. Retry.
    503
    Temporarily unavailable, for example the token could not be checked, the gateway could not confirm its own account setup (operator_unresolved, with a Retry-After header), or a call made under a phone lane reached the lane's deadline (lane_reclaimed, with a Retry-After header and ambiguous). Unless the error explicitly says nothing was sent (for example ambiguous: false), treat any write as possibly applied; list or read the state of what you changed before retrying a write; never re-create (e.g. a group) without reading/listing first; reads can be retried after a short back-off. Honor Retry-After when present.

  • GET/v1/sessions/{name}/groups/{group}

    Get a group

    Parameters

    name (path, required)
    Channel ID.
    group (path, required)
    Group JID.

    Responses

    200
    OK
    400
    The request was refused as sent.
    401
    Missing, invalid or stale token, or a channel this token does not open.
    403
    The token is valid and may not do this.
    404
    The route or the named object does not exist.
    409
    The channel's state does not allow this, for example not_linked or stood_down.
    429
    A gateway flood guard or the webhook-test cooldown (rate_limited, with a Retry-After header), the gateway being busy with this channel's earlier requests (gateway_busy, Retry-After: 1), a sandbox channel's allowance (sandbox_allowance_exceeded, with Retry-After), an operator stop (daily_send_cap_exceeded), an optional warm-up protection allowance (daily_cap_<class>, only when warm-up protection is on), a history request inside its rate limit (history_request_too_soon, with Retry-After), or WhatsApp throttling the number (whatsapp_rate_limited, no Retry-After). Paid numbers have no gateway allowance. code says which: the bodies never share one.
    500
    The gateway could not complete the request.
    502
    The service behind the gateway could not be reached or answered unusably. Retry.
    503
    Temporarily unavailable, for example the token could not be checked, the gateway could not confirm its own account setup (operator_unresolved, with a Retry-After header), or a call made under a phone lane reached the lane's deadline (lane_reclaimed, with a Retry-After header and ambiguous). Unless the error explicitly says nothing was sent (for example ambiguous: false), treat any write as possibly applied; list or read the state of what you changed before retrying a write; never re-create (e.g. a group) without reading/listing first; reads can be retried after a short back-off. Honor Retry-After when present.

  • PUT/v1/sessions/{name}/groups/{group}/description

    Set or clear a group's description

    Parameters

    name (path, required)
    Channel ID.
    group (path, required)
    Group JID.

    Request body

    description (string, required)
    An empty string removes the description.

    Responses

    200
    OK
    400
    The request was refused as sent.
    401
    Missing, invalid or stale token, or a channel this token does not open.
    403
    The token is valid and may not do this.
    404
    The route or the named object does not exist.
    409
    The channel's state does not allow this, for example not_linked or stood_down.
    429
    A gateway flood guard or the webhook-test cooldown (rate_limited, with a Retry-After header), the gateway being busy with this channel's earlier requests (gateway_busy, Retry-After: 1), a sandbox channel's allowance (sandbox_allowance_exceeded, with Retry-After), an operator stop (daily_send_cap_exceeded), an optional warm-up protection allowance (daily_cap_<class>, only when warm-up protection is on), a history request inside its rate limit (history_request_too_soon, with Retry-After), or WhatsApp throttling the number (whatsapp_rate_limited, no Retry-After). Paid numbers have no gateway allowance. code says which: the bodies never share one.
    500
    The gateway could not complete the request.
    502
    The service behind the gateway could not be reached or answered unusably. Retry.
    503
    Temporarily unavailable, for example the token could not be checked, the gateway could not confirm its own account setup (operator_unresolved, with a Retry-After header), or a call made under a phone lane reached the lane's deadline (lane_reclaimed, with a Retry-After header and ambiguous). Unless the error explicitly says nothing was sent (for example ambiguous: false), treat any write as possibly applied; list or read the state of what you changed before retrying a write; never re-create (e.g. a group) without reading/listing first; reads can be retried after a short back-off. Honor Retry-After when present.

  • POST/v1/sessions/{name}/groups/{group}/participants

    Add, remove, promote or demote participants

    Parameters

    name (path, required)
    Channel ID.
    group (path, required)
    Group JID.

    Request body

    action (string, required)
    participants (array of string, required)

    Responses

    200
    OK
    400
    The request was refused as sent.
    401
    Missing, invalid or stale token, or a channel this token does not open.
    403
    The token is valid and may not do this.
    404
    The route or the named object does not exist.
    409
    The channel's state does not allow this, for example not_linked or stood_down.
    429
    A gateway flood guard or the webhook-test cooldown (rate_limited, with a Retry-After header), the gateway being busy with this channel's earlier requests (gateway_busy, Retry-After: 1), a sandbox channel's allowance (sandbox_allowance_exceeded, with Retry-After), an operator stop (daily_send_cap_exceeded), an optional warm-up protection allowance (daily_cap_<class>, only when warm-up protection is on), a history request inside its rate limit (history_request_too_soon, with Retry-After), or WhatsApp throttling the number (whatsapp_rate_limited, no Retry-After). Paid numbers have no gateway allowance. code says which: the bodies never share one.
    500
    The gateway could not complete the request.
    502
    The service behind the gateway could not be reached or answered unusably. Retry.
    503
    Temporarily unavailable, for example the token could not be checked, the gateway could not confirm its own account setup (operator_unresolved, with a Retry-After header), or a call made under a phone lane reached the lane's deadline (lane_reclaimed, with a Retry-After header and ambiguous). Unless the error explicitly says nothing was sent (for example ambiguous: false), treat any write as possibly applied; list or read the state of what you changed before retrying a write; never re-create (e.g. a group) without reading/listing first; reads can be retried after a short back-off. Honor Retry-After when present.

  • PUT/v1/sessions/{name}/groups/{group}/settings

    Change a group's settings

    Parameters

    name (path, required)
    Channel ID.
    group (path, required)
    Group JID.

    Request body

    announce (boolean)
    locked (boolean)
    member_add_mode (string)

    Responses

    200
    OK
    400
    The request was refused as sent.
    401
    Missing, invalid or stale token, or a channel this token does not open.
    403
    The token is valid and may not do this.
    404
    The route or the named object does not exist.
    409
    The channel's state does not allow this, for example not_linked or stood_down.
    429
    A gateway flood guard or the webhook-test cooldown (rate_limited, with a Retry-After header), the gateway being busy with this channel's earlier requests (gateway_busy, Retry-After: 1), a sandbox channel's allowance (sandbox_allowance_exceeded, with Retry-After), an operator stop (daily_send_cap_exceeded), an optional warm-up protection allowance (daily_cap_<class>, only when warm-up protection is on), a history request inside its rate limit (history_request_too_soon, with Retry-After), or WhatsApp throttling the number (whatsapp_rate_limited, no Retry-After). Paid numbers have no gateway allowance. code says which: the bodies never share one.
    500
    The gateway could not complete the request.
    502
    The service behind the gateway could not be reached or answered unusably. Retry.
    503
    Temporarily unavailable, for example the token could not be checked, the gateway could not confirm its own account setup (operator_unresolved, with a Retry-After header), or a call made under a phone lane reached the lane's deadline (lane_reclaimed, with a Retry-After header and ambiguous). Unless the error explicitly says nothing was sent (for example ambiguous: false), treat any write as possibly applied; list or read the state of what you changed before retrying a write; never re-create (e.g. a group) without reading/listing first; reads can be retried after a short back-off. Honor Retry-After when present.

  • PUT/v1/sessions/{name}/groups/{group}/subject

    Set a group's subject

    Parameters

    name (path, required)
    Channel ID.
    group (path, required)
    Group JID.

    Request body

    subject (string, required)

    Responses

    200
    OK
    400
    The request was refused as sent.
    401
    Missing, invalid or stale token, or a channel this token does not open.
    403
    The token is valid and may not do this.
    404
    The route or the named object does not exist.
    409
    The channel's state does not allow this, for example not_linked or stood_down.
    429
    A gateway flood guard or the webhook-test cooldown (rate_limited, with a Retry-After header), the gateway being busy with this channel's earlier requests (gateway_busy, Retry-After: 1), a sandbox channel's allowance (sandbox_allowance_exceeded, with Retry-After), an operator stop (daily_send_cap_exceeded), an optional warm-up protection allowance (daily_cap_<class>, only when warm-up protection is on), a history request inside its rate limit (history_request_too_soon, with Retry-After), or WhatsApp throttling the number (whatsapp_rate_limited, no Retry-After). Paid numbers have no gateway allowance. code says which: the bodies never share one.
    500
    The gateway could not complete the request.
    502
    The service behind the gateway could not be reached or answered unusably. Retry.
    503
    Temporarily unavailable, for example the token could not be checked, the gateway could not confirm its own account setup (operator_unresolved, with a Retry-After header), or a call made under a phone lane reached the lane's deadline (lane_reclaimed, with a Retry-After header and ambiguous). Unless the error explicitly says nothing was sent (for example ambiguous: false), treat any write as possibly applied; list or read the state of what you changed before retrying a write; never re-create (e.g. a group) without reading/listing first; reads can be retried after a short back-off. Honor Retry-After when present.

Communities

  • POST/v1/sessions/{name}/communities

    Create a community

    Parameters

    name (path, required)
    Channel ID.

    Request body

    subject (string, required)

    Responses

    201
    Created
    400
    The request was refused as sent.
    401
    Missing, invalid or stale token, or a channel this token does not open.
    403
    The token is valid and may not do this.
    404
    The route or the named object does not exist.
    409
    The channel's state does not allow this, for example not_linked or stood_down.
    429
    A gateway flood guard or the webhook-test cooldown (rate_limited, with a Retry-After header), the gateway being busy with this channel's earlier requests (gateway_busy, Retry-After: 1), a sandbox channel's allowance (sandbox_allowance_exceeded, with Retry-After), an operator stop (daily_send_cap_exceeded), an optional warm-up protection allowance (daily_cap_<class>, only when warm-up protection is on), a history request inside its rate limit (history_request_too_soon, with Retry-After), or WhatsApp throttling the number (whatsapp_rate_limited, no Retry-After). Paid numbers have no gateway allowance. code says which: the bodies never share one.
    500
    The gateway could not complete the request.
    502
    The service behind the gateway could not be reached or answered unusably. Retry.
    503
    Temporarily unavailable, for example the token could not be checked, the gateway could not confirm its own account setup (operator_unresolved, with a Retry-After header), or a call made under a phone lane reached the lane's deadline (lane_reclaimed, with a Retry-After header and ambiguous). Unless the error explicitly says nothing was sent (for example ambiguous: false), treat any write as possibly applied; list or read the state of what you changed before retrying a write; never re-create (e.g. a group) without reading/listing first; reads can be retried after a short back-off. Honor Retry-After when present.

  • GET/v1/sessions/{name}/communities/{community}

    Get a community

    Parameters

    name (path, required)
    Channel ID.
    community (path, required)
    Community JID.

    Responses

    200
    OK
    400
    The request was refused as sent.
    401
    Missing, invalid or stale token, or a channel this token does not open.
    403
    The token is valid and may not do this.
    404
    The route or the named object does not exist.
    409
    The channel's state does not allow this, for example not_linked or stood_down.
    429
    A gateway flood guard or the webhook-test cooldown (rate_limited, with a Retry-After header), the gateway being busy with this channel's earlier requests (gateway_busy, Retry-After: 1), a sandbox channel's allowance (sandbox_allowance_exceeded, with Retry-After), an operator stop (daily_send_cap_exceeded), an optional warm-up protection allowance (daily_cap_<class>, only when warm-up protection is on), a history request inside its rate limit (history_request_too_soon, with Retry-After), or WhatsApp throttling the number (whatsapp_rate_limited, no Retry-After). Paid numbers have no gateway allowance. code says which: the bodies never share one.
    500
    The gateway could not complete the request.
    502
    The service behind the gateway could not be reached or answered unusably. Retry.
    503
    Temporarily unavailable, for example the token could not be checked, the gateway could not confirm its own account setup (operator_unresolved, with a Retry-After header), or a call made under a phone lane reached the lane's deadline (lane_reclaimed, with a Retry-After header and ambiguous). Unless the error explicitly says nothing was sent (for example ambiguous: false), treat any write as possibly applied; list or read the state of what you changed before retrying a write; never re-create (e.g. a group) without reading/listing first; reads can be retried after a short back-off. Honor Retry-After when present.

  • POST/v1/sessions/{name}/communities/{community}/links

    Link a group to a community

    Parameters

    name (path, required)
    Channel ID.
    community (path, required)
    Community JID.

    Request body

    group_jid (string, required)
    hidden (boolean)

    Responses

    200
    OK
    400
    The request was refused as sent.
    401
    Missing, invalid or stale token, or a channel this token does not open.
    403
    The token is valid and may not do this.
    404
    The route or the named object does not exist.
    409
    The channel's state does not allow this, for example not_linked or stood_down.
    429
    A gateway flood guard or the webhook-test cooldown (rate_limited, with a Retry-After header), the gateway being busy with this channel's earlier requests (gateway_busy, Retry-After: 1), a sandbox channel's allowance (sandbox_allowance_exceeded, with Retry-After), an operator stop (daily_send_cap_exceeded), an optional warm-up protection allowance (daily_cap_<class>, only when warm-up protection is on), a history request inside its rate limit (history_request_too_soon, with Retry-After), or WhatsApp throttling the number (whatsapp_rate_limited, no Retry-After). Paid numbers have no gateway allowance. code says which: the bodies never share one.
    500
    The gateway could not complete the request.
    502
    The service behind the gateway could not be reached or answered unusably. Retry.
    503
    Temporarily unavailable, for example the token could not be checked, the gateway could not confirm its own account setup (operator_unresolved, with a Retry-After header), or a call made under a phone lane reached the lane's deadline (lane_reclaimed, with a Retry-After header and ambiguous). Unless the error explicitly says nothing was sent (for example ambiguous: false), treat any write as possibly applied; list or read the state of what you changed before retrying a write; never re-create (e.g. a group) without reading/listing first; reads can be retried after a short back-off. Honor Retry-After when present.

  • DELETE/v1/sessions/{name}/communities/{community}/links/{group}

    Unlink a group from a community

    Parameters

    name (path, required)
    Channel ID.
    community (path, required)
    Community JID.
    group (path, required)
    Group JID.

    Responses

    200
    OK
    400
    The request was refused as sent.
    401
    Missing, invalid or stale token, or a channel this token does not open.
    403
    The token is valid and may not do this.
    404
    The route or the named object does not exist.
    409
    The channel's state does not allow this, for example not_linked or stood_down.
    429
    A gateway flood guard or the webhook-test cooldown (rate_limited, with a Retry-After header), the gateway being busy with this channel's earlier requests (gateway_busy, Retry-After: 1), a sandbox channel's allowance (sandbox_allowance_exceeded, with Retry-After), an operator stop (daily_send_cap_exceeded), an optional warm-up protection allowance (daily_cap_<class>, only when warm-up protection is on), a history request inside its rate limit (history_request_too_soon, with Retry-After), or WhatsApp throttling the number (whatsapp_rate_limited, no Retry-After). Paid numbers have no gateway allowance. code says which: the bodies never share one.
    500
    The gateway could not complete the request.
    502
    The service behind the gateway could not be reached or answered unusably. Retry.
    503
    Temporarily unavailable, for example the token could not be checked, the gateway could not confirm its own account setup (operator_unresolved, with a Retry-After header), or a call made under a phone lane reached the lane's deadline (lane_reclaimed, with a Retry-After header and ambiguous). Unless the error explicitly says nothing was sent (for example ambiguous: false), treat any write as possibly applied; list or read the state of what you changed before retrying a write; never re-create (e.g. a group) without reading/listing first; reads can be retried after a short back-off. Honor Retry-After when present.

  • GET/v1/sessions/{name}/communities/{community}/participants

    List a community's participants

    Parameters

    name (path, required)
    Channel ID.
    community (path, required)
    Community JID.

    Responses

    200
    OK
    400
    The request was refused as sent.
    401
    Missing, invalid or stale token, or a channel this token does not open.
    403
    The token is valid and may not do this.
    404
    The route or the named object does not exist.
    409
    The channel's state does not allow this, for example not_linked or stood_down.
    429
    A gateway flood guard or the webhook-test cooldown (rate_limited, with a Retry-After header), the gateway being busy with this channel's earlier requests (gateway_busy, Retry-After: 1), a sandbox channel's allowance (sandbox_allowance_exceeded, with Retry-After), an operator stop (daily_send_cap_exceeded), an optional warm-up protection allowance (daily_cap_<class>, only when warm-up protection is on), a history request inside its rate limit (history_request_too_soon, with Retry-After), or WhatsApp throttling the number (whatsapp_rate_limited, no Retry-After). Paid numbers have no gateway allowance. code says which: the bodies never share one.
    500
    The gateway could not complete the request.
    502
    The service behind the gateway could not be reached or answered unusably. Retry.
    503
    Temporarily unavailable, for example the token could not be checked, the gateway could not confirm its own account setup (operator_unresolved, with a Retry-After header), or a call made under a phone lane reached the lane's deadline (lane_reclaimed, with a Retry-After header and ambiguous). Unless the error explicitly says nothing was sent (for example ambiguous: false), treat any write as possibly applied; list or read the state of what you changed before retrying a write; never re-create (e.g. a group) without reading/listing first; reads can be retried after a short back-off. Honor Retry-After when present.

  • GET/v1/sessions/{name}/communities/{community}/subgroups

    List a community's subgroups

    Parameters

    name (path, required)
    Channel ID.
    community (path, required)
    Community JID.

    Responses

    200
    OK
    400
    The request was refused as sent.
    401
    Missing, invalid or stale token, or a channel this token does not open.
    403
    The token is valid and may not do this.
    404
    The route or the named object does not exist.
    409
    The channel's state does not allow this, for example not_linked or stood_down.
    429
    A gateway flood guard or the webhook-test cooldown (rate_limited, with a Retry-After header), the gateway being busy with this channel's earlier requests (gateway_busy, Retry-After: 1), a sandbox channel's allowance (sandbox_allowance_exceeded, with Retry-After), an operator stop (daily_send_cap_exceeded), an optional warm-up protection allowance (daily_cap_<class>, only when warm-up protection is on), a history request inside its rate limit (history_request_too_soon, with Retry-After), or WhatsApp throttling the number (whatsapp_rate_limited, no Retry-After). Paid numbers have no gateway allowance. code says which: the bodies never share one.
    500
    The gateway could not complete the request.
    502
    The service behind the gateway could not be reached or answered unusably. Retry.
    503
    Temporarily unavailable, for example the token could not be checked, the gateway could not confirm its own account setup (operator_unresolved, with a Retry-After header), or a call made under a phone lane reached the lane's deadline (lane_reclaimed, with a Retry-After header and ambiguous). Unless the error explicitly says nothing was sent (for example ambiguous: false), treat any write as possibly applied; list or read the state of what you changed before retrying a write; never re-create (e.g. a group) without reading/listing first; reads can be retried after a short back-off. Honor Retry-After when present.

  • POST/v1/sessions/{name}/communities/{community}/subgroups

    Create a subgroup in a community

    Parameters

    name (path, required)
    Channel ID.
    community (path, required)
    Community JID.

    Request body

    subject (string, required)
    participants (array of string)
    hidden (boolean)

    Responses

    201
    Created
    400
    The request was refused as sent.
    401
    Missing, invalid or stale token, or a channel this token does not open.
    403
    The token is valid and may not do this.
    404
    The route or the named object does not exist.
    409
    The channel's state does not allow this, or the subgroup was created and verification definitively failed.
    429
    A gateway flood guard or the webhook-test cooldown (rate_limited, with a Retry-After header), the gateway being busy with this channel's earlier requests (gateway_busy, Retry-After: 1), a sandbox channel's allowance (sandbox_allowance_exceeded, with Retry-After), an operator stop (daily_send_cap_exceeded), an optional warm-up protection allowance (daily_cap_<class>, only when warm-up protection is on), a history request inside its rate limit (history_request_too_soon, with Retry-After), or WhatsApp throttling the number (whatsapp_rate_limited, no Retry-After). Paid numbers have no gateway allowance. code says which: the bodies never share one.
    500
    The gateway could not complete the request.
    502
    The service behind the gateway could not be reached or answered unusably. Retry.
    503
    Temporarily unavailable, for example the token could not be checked, the gateway could not confirm its own account setup (operator_unresolved, with a Retry-After header), or a call made under a phone lane reached the lane's deadline (lane_reclaimed, with a Retry-After header and ambiguous). Unless the error explicitly says nothing was sent (for example ambiguous: false), treat any write as possibly applied; list or read the state of what you changed before retrying a write; never re-create (e.g. a group) without reading/listing first; reads can be retried after a short back-off. Honor Retry-After when present.

Contacts

  • POST/v1/sessions/{name}/contacts/check

    Check which phone numbers are on WhatsApp

    Parameters

    name (path, required)
    Channel ID.

    Request body

    phones (array of string, required)

    Responses

    200
    OK
    400
    The request was refused as sent.
    401
    Missing, invalid or stale token, or a channel this token does not open.
    403
    The token is valid and may not do this.
    404
    The route or the named object does not exist.
    409
    The channel's state does not allow this, for example not_linked or stood_down.
    429
    A gateway flood guard or the webhook-test cooldown (rate_limited, with a Retry-After header), the gateway being busy with this channel's earlier requests (gateway_busy, Retry-After: 1), a sandbox channel's allowance (sandbox_allowance_exceeded, with Retry-After), an operator stop (daily_send_cap_exceeded), an optional warm-up protection allowance (daily_cap_<class>, only when warm-up protection is on), a history request inside its rate limit (history_request_too_soon, with Retry-After), or WhatsApp throttling the number (whatsapp_rate_limited, no Retry-After). Paid numbers have no gateway allowance. code says which: the bodies never share one.
    500
    The gateway could not complete the request.
    502
    The service behind the gateway could not be reached or answered unusably. Retry.
    503
    Temporarily unavailable, for example the token could not be checked, the gateway could not confirm its own account setup (operator_unresolved, with a Retry-After header), or a call made under a phone lane reached the lane's deadline (lane_reclaimed, with a Retry-After header and ambiguous). Unless the error explicitly says nothing was sent (for example ambiguous: false), treat any write as possibly applied; list or read the state of what you changed before retrying a write; never re-create (e.g. a group) without reading/listing first; reads can be retried after a short back-off. Honor Retry-After when present.

  • GET/v1/sessions/{name}/contacts/{who}

    Get a contact

    Parameters

    name (path, required)
    Channel ID.
    who (path, required)
    Contact address: a user JID or a LID.

    Responses

    200
    OK
    400
    The request was refused as sent.
    401
    Missing, invalid or stale token, or a channel this token does not open.
    403
    The token is valid and may not do this.
    404
    The route or the named object does not exist.
    409
    The channel's state does not allow this, for example not_linked or stood_down.
    429
    A gateway flood guard or the webhook-test cooldown (rate_limited, with a Retry-After header), the gateway being busy with this channel's earlier requests (gateway_busy, Retry-After: 1), a sandbox channel's allowance (sandbox_allowance_exceeded, with Retry-After), an operator stop (daily_send_cap_exceeded), an optional warm-up protection allowance (daily_cap_<class>, only when warm-up protection is on), a history request inside its rate limit (history_request_too_soon, with Retry-After), or WhatsApp throttling the number (whatsapp_rate_limited, no Retry-After). Paid numbers have no gateway allowance. code says which: the bodies never share one.
    500
    The gateway could not complete the request.
    502
    The service behind the gateway could not be reached or answered unusably. Retry.
    503
    Temporarily unavailable, for example the token could not be checked, the gateway could not confirm its own account setup (operator_unresolved, with a Retry-After header), or a call made under a phone lane reached the lane's deadline (lane_reclaimed, with a Retry-After header and ambiguous). Unless the error explicitly says nothing was sent (for example ambiguous: false), treat any write as possibly applied; list or read the state of what you changed before retrying a write; never re-create (e.g. a group) without reading/listing first; reads can be retried after a short back-off. Honor Retry-After when present.

  • PUT/v1/sessions/{name}/contacts/{who}

    Save or update a contact

    Parameters

    name (path, required)
    Channel ID.
    who (path, required)
    Contact address: a user JID or a LID.

    Request body

    full_name (string, required)
    first_name (string)

    Responses

    200
    OK
    400
    The request was refused as sent.
    401
    Missing, invalid or stale token, or a channel this token does not open.
    403
    The token is valid and may not do this.
    404
    The route or the named object does not exist.
    409
    The channel's state does not allow this, for example not_linked or stood_down.
    429
    A gateway flood guard or the webhook-test cooldown (rate_limited, with a Retry-After header), the gateway being busy with this channel's earlier requests (gateway_busy, Retry-After: 1), a sandbox channel's allowance (sandbox_allowance_exceeded, with Retry-After), an operator stop (daily_send_cap_exceeded), an optional warm-up protection allowance (daily_cap_<class>, only when warm-up protection is on), a history request inside its rate limit (history_request_too_soon, with Retry-After), or WhatsApp throttling the number (whatsapp_rate_limited, no Retry-After). Paid numbers have no gateway allowance. code says which: the bodies never share one.
    500
    The gateway could not complete the request.
    502
    The service behind the gateway could not be reached or answered unusably. Retry.
    503
    Temporarily unavailable, for example the token could not be checked, the gateway could not confirm its own account setup (operator_unresolved, with a Retry-After header), or a call made under a phone lane reached the lane's deadline (lane_reclaimed, with a Retry-After header and ambiguous). Unless the error explicitly says nothing was sent (for example ambiguous: false), treat any write as possibly applied; list or read the state of what you changed before retrying a write; never re-create (e.g. a group) without reading/listing first; reads can be retried after a short back-off. Honor Retry-After when present.

  • DELETE/v1/sessions/{name}/contacts/{who}

    Remove a contact

    Parameters

    name (path, required)
    Channel ID.
    who (path, required)
    Contact address: a user JID or a LID.

    Responses

    200
    OK
    400
    The request was refused as sent.
    401
    Missing, invalid or stale token, or a channel this token does not open.
    403
    The token is valid and may not do this.
    404
    The route or the named object does not exist.
    409
    The channel's state does not allow this, for example not_linked or stood_down.
    429
    A gateway flood guard or the webhook-test cooldown (rate_limited, with a Retry-After header), the gateway being busy with this channel's earlier requests (gateway_busy, Retry-After: 1), a sandbox channel's allowance (sandbox_allowance_exceeded, with Retry-After), an operator stop (daily_send_cap_exceeded), an optional warm-up protection allowance (daily_cap_<class>, only when warm-up protection is on), a history request inside its rate limit (history_request_too_soon, with Retry-After), or WhatsApp throttling the number (whatsapp_rate_limited, no Retry-After). Paid numbers have no gateway allowance. code says which: the bodies never share one.
    500
    The gateway could not complete the request.
    502
    The service behind the gateway could not be reached or answered unusably. Retry.
    503
    Temporarily unavailable, for example the token could not be checked, the gateway could not confirm its own account setup (operator_unresolved, with a Retry-After header), or a call made under a phone lane reached the lane's deadline (lane_reclaimed, with a Retry-After header and ambiguous). Unless the error explicitly says nothing was sent (for example ambiguous: false), treat any write as possibly applied; list or read the state of what you changed before retrying a write; never re-create (e.g. a group) without reading/listing first; reads can be retried after a short back-off. Honor Retry-After when present.

  • GET/v1/sessions/{name}/lids/pn/{phone}

    Look up the LID for a phone number

    Parameters

    name (path, required)
    Channel ID.
    phone (path, required)
    Phone number, digits with an optional leading +.

    Responses

    200
    OK
    400
    The request was refused as sent.
    401
    Missing, invalid or stale token, or a channel this token does not open.
    403
    The token is valid and may not do this.
    404
    The route or the named object does not exist.
    409
    The channel's state does not allow this, for example not_linked or stood_down.
    429
    A gateway flood guard or the webhook-test cooldown (rate_limited, with a Retry-After header), the gateway being busy with this channel's earlier requests (gateway_busy, Retry-After: 1), a sandbox channel's allowance (sandbox_allowance_exceeded, with Retry-After), an operator stop (daily_send_cap_exceeded), an optional warm-up protection allowance (daily_cap_<class>, only when warm-up protection is on), a history request inside its rate limit (history_request_too_soon, with Retry-After), or WhatsApp throttling the number (whatsapp_rate_limited, no Retry-After). Paid numbers have no gateway allowance. code says which: the bodies never share one.
    500
    The gateway could not complete the request.
    502
    The service behind the gateway could not be reached or answered unusably. Retry.
    503
    Temporarily unavailable, for example the token could not be checked, the gateway could not confirm its own account setup (operator_unresolved, with a Retry-After header), or a call made under a phone lane reached the lane's deadline (lane_reclaimed, with a Retry-After header and ambiguous). Unless the error explicitly says nothing was sent (for example ambiguous: false), treat any write as possibly applied; list or read the state of what you changed before retrying a write; never re-create (e.g. a group) without reading/listing first; reads can be retried after a short back-off. Honor Retry-After when present.

  • GET/v1/sessions/{name}/lids/{lid}

    Look up the phone number for a LID

    Parameters

    name (path, required)
    Channel ID.
    lid (path, required)
    A LID: digits followed by the literal @lid.

    Responses

    200
    OK
    400
    The request was refused as sent.
    401
    Missing, invalid or stale token, or a channel this token does not open.
    403
    The token is valid and may not do this.
    404
    The route or the named object does not exist.
    409
    The channel's state does not allow this, for example not_linked or stood_down.
    429
    A gateway flood guard or the webhook-test cooldown (rate_limited, with a Retry-After header), the gateway being busy with this channel's earlier requests (gateway_busy, Retry-After: 1), a sandbox channel's allowance (sandbox_allowance_exceeded, with Retry-After), an operator stop (daily_send_cap_exceeded), an optional warm-up protection allowance (daily_cap_<class>, only when warm-up protection is on), a history request inside its rate limit (history_request_too_soon, with Retry-After), or WhatsApp throttling the number (whatsapp_rate_limited, no Retry-After). Paid numbers have no gateway allowance. code says which: the bodies never share one.
    500
    The gateway could not complete the request.
    502
    The service behind the gateway could not be reached or answered unusably. Retry.
    503
    Temporarily unavailable, for example the token could not be checked, the gateway could not confirm its own account setup (operator_unresolved, with a Retry-After header), or a call made under a phone lane reached the lane's deadline (lane_reclaimed, with a Retry-After header and ambiguous). Unless the error explicitly says nothing was sent (for example ambiguous: false), treat any write as possibly applied; list or read the state of what you changed before retrying a write; never re-create (e.g. a group) without reading/listing first; reads can be retried after a short back-off. Honor Retry-After when present.

Channel

  • GET/v1/health

    Liveness

    Responses

    200
    OK

  • GET/v1/sessions/{name}

    Read this channel's state

    Parameters

    name (path, required)
    Channel ID.

    Responses

    200
    OK
    400
    The request was refused as sent.
    401
    Missing, invalid or stale token, or a channel this token does not open.
    404
    The route or the named object does not exist.
    429
    A gateway flood guard or the webhook-test cooldown (rate_limited, with a Retry-After header), the gateway being busy with this channel's earlier requests (gateway_busy, Retry-After: 1), a sandbox channel's allowance (sandbox_allowance_exceeded, with Retry-After), an operator stop (daily_send_cap_exceeded), an optional warm-up protection allowance (daily_cap_<class>, only when warm-up protection is on), a history request inside its rate limit (history_request_too_soon, with Retry-After), or WhatsApp throttling the number (whatsapp_rate_limited, no Retry-After). Paid numbers have no gateway allowance. code says which: the bodies never share one.
    500
    The gateway could not complete the request.
    502
    The service behind the gateway could not be reached or answered unusably. Retry.
    503
    Temporarily unavailable, for example the token could not be checked, the gateway could not confirm its own account setup (operator_unresolved, with a Retry-After header), or a call made under a phone lane reached the lane's deadline (lane_reclaimed, with a Retry-After header and ambiguous). Unless the error explicitly says nothing was sent (for example ambiguous: false), treat any write as possibly applied; list or read the state of what you changed before retrying a write; never re-create (e.g. a group) without reading/listing first; reads can be retried after a short back-off. Honor Retry-After when present.

  • PATCH/v1/sessions/{name}

    Change this channel's label or registration date

    Parameters

    name (path, required)
    Channel ID.

    Request body

    label (string)
    An empty string resets it.
    registration_date (string)
    YYYY-MM-DD, not in the future. An empty string resets it.

    Responses

    200
    OK
    400
    The request was refused as sent.
    401
    Missing, invalid or stale token, or a channel this token does not open.
    403
    The token is valid and may not do this.
    404
    The route or the named object does not exist.
    429
    A gateway flood guard or the webhook-test cooldown (rate_limited, with a Retry-After header), the gateway being busy with this channel's earlier requests (gateway_busy, Retry-After: 1), a sandbox channel's allowance (sandbox_allowance_exceeded, with Retry-After), an operator stop (daily_send_cap_exceeded), an optional warm-up protection allowance (daily_cap_<class>, only when warm-up protection is on), a history request inside its rate limit (history_request_too_soon, with Retry-After), or WhatsApp throttling the number (whatsapp_rate_limited, no Retry-After). Paid numbers have no gateway allowance. code says which: the bodies never share one.
    500
    The gateway could not complete the request.
    502
    The service behind the gateway could not be reached or answered unusably. Retry.
    503
    Temporarily unavailable, for example the token could not be checked, the gateway could not confirm its own account setup (operator_unresolved, with a Retry-After header), or a call made under a phone lane reached the lane's deadline (lane_reclaimed, with a Retry-After header and ambiguous). Unless the error explicitly says nothing was sent (for example ambiguous: false), treat any write as possibly applied; list or read the state of what you changed before retrying a write; never re-create (e.g. a group) without reading/listing first; reads can be retried after a short back-off. Honor Retry-After when present.

  • GET/v1/sessions/{name}/safety

    Read this channel's health readings

    Parameters

    name (path, required)
    Channel ID.

    Responses

    200
    OK
    400
    The request was refused as sent.
    401
    Missing, invalid or stale token, or a channel this token does not open.
    404
    The route or the named object does not exist.
    429
    A gateway flood guard or the webhook-test cooldown (rate_limited, with a Retry-After header), the gateway being busy with this channel's earlier requests (gateway_busy, Retry-After: 1), a sandbox channel's allowance (sandbox_allowance_exceeded, with Retry-After), an operator stop (daily_send_cap_exceeded), an optional warm-up protection allowance (daily_cap_<class>, only when warm-up protection is on), a history request inside its rate limit (history_request_too_soon, with Retry-After), or WhatsApp throttling the number (whatsapp_rate_limited, no Retry-After). Paid numbers have no gateway allowance. code says which: the bodies never share one.
    500
    The gateway could not complete the request.
    502
    The service behind the gateway could not be reached or answered unusably. Retry.
    503
    Temporarily unavailable, for example the token could not be checked, the gateway could not confirm its own account setup (operator_unresolved, with a Retry-After header), or a call made under a phone lane reached the lane's deadline (lane_reclaimed, with a Retry-After header and ambiguous). Unless the error explicitly says nothing was sent (for example ambiguous: false), treat any write as possibly applied; list or read the state of what you changed before retrying a write; never re-create (e.g. a group) without reading/listing first; reads can be retried after a short back-off. Honor Retry-After when present.

Webhooks

  • GET/v1/sessions/{name}/webhooks

    List this channel's webhook receivers

    Parameters

    name (path, required)
    Channel ID.

    Responses

    200
    OK
    400
    The request was refused as sent.
    401
    Missing, invalid or stale token, or a channel this token does not open.
    404
    The route or the named object does not exist.
    429
    A gateway flood guard or the webhook-test cooldown (rate_limited, with a Retry-After header), the gateway being busy with this channel's earlier requests (gateway_busy, Retry-After: 1), a sandbox channel's allowance (sandbox_allowance_exceeded, with Retry-After), an operator stop (daily_send_cap_exceeded), an optional warm-up protection allowance (daily_cap_<class>, only when warm-up protection is on), a history request inside its rate limit (history_request_too_soon, with Retry-After), or WhatsApp throttling the number (whatsapp_rate_limited, no Retry-After). Paid numbers have no gateway allowance. code says which: the bodies never share one.
    500
    The gateway could not complete the request.
    502
    The service behind the gateway could not be reached or answered unusably. Retry.
    503
    Temporarily unavailable, for example the token could not be checked, the gateway could not confirm its own account setup (operator_unresolved, with a Retry-After header), or a call made under a phone lane reached the lane's deadline (lane_reclaimed, with a Retry-After header and ambiguous). Unless the error explicitly says nothing was sent (for example ambiguous: false), treat any write as possibly applied; list or read the state of what you changed before retrying a write; never re-create (e.g. a group) without reading/listing first; reads can be retried after a short back-off. Honor Retry-After when present.

  • PUT/v1/sessions/{name}/webhooks

    Replace this channel's webhook receivers

    Parameters

    name (path, required)
    Channel ID.

    Request body

    receivers (array of object, required)
    Replaces the whole list. An empty list removes every receiver.

    Responses

    200
    OK
    400
    The request was refused as sent.
    401
    Missing, invalid or stale token, or a channel this token does not open.
    403
    The token is valid and may not do this.
    404
    The route or the named object does not exist.
    429
    A gateway flood guard or the webhook-test cooldown (rate_limited, with a Retry-After header), the gateway being busy with this channel's earlier requests (gateway_busy, Retry-After: 1), a sandbox channel's allowance (sandbox_allowance_exceeded, with Retry-After), an operator stop (daily_send_cap_exceeded), an optional warm-up protection allowance (daily_cap_<class>, only when warm-up protection is on), a history request inside its rate limit (history_request_too_soon, with Retry-After), or WhatsApp throttling the number (whatsapp_rate_limited, no Retry-After). Paid numbers have no gateway allowance. code says which: the bodies never share one.
    500
    The gateway could not complete the request.
    502
    The service behind the gateway could not be reached or answered unusably. Retry.
    503
    Temporarily unavailable, for example the token could not be checked, the gateway could not confirm its own account setup (operator_unresolved, with a Retry-After header), or a call made under a phone lane reached the lane's deadline (lane_reclaimed, with a Retry-After header and ambiguous). Unless the error explicitly says nothing was sent (for example ambiguous: false), treat any write as possibly applied; list or read the state of what you changed before retrying a write; never re-create (e.g. a group) without reading/listing first; reads can be retried after a short back-off. Honor Retry-After when present.

  • POST/v1/sessions/{name}/webhooks/test

    Send one signed test event to a configured receiver

    Parameters

    name (path, required)
    Channel ID.

    Request body

    url (string, required)

    Responses

    200
    OK
    400
    The request was refused as sent.
    401
    Missing, invalid or stale token, or a channel this token does not open.
    404
    The route or the named object does not exist.
    429
    A gateway flood guard or the webhook-test cooldown (rate_limited, with a Retry-After header), the gateway being busy with this channel's earlier requests (gateway_busy, Retry-After: 1), a sandbox channel's allowance (sandbox_allowance_exceeded, with Retry-After), an operator stop (daily_send_cap_exceeded), an optional warm-up protection allowance (daily_cap_<class>, only when warm-up protection is on), a history request inside its rate limit (history_request_too_soon, with Retry-After), or WhatsApp throttling the number (whatsapp_rate_limited, no Retry-After). Paid numbers have no gateway allowance. code says which: the bodies never share one.
    500
    The gateway could not complete the request.
    502
    The service behind the gateway could not be reached or answered unusably. Retry.
    503
    Temporarily unavailable, for example the token could not be checked, the gateway could not confirm its own account setup (operator_unresolved, with a Retry-After header), or a call made under a phone lane reached the lane's deadline (lane_reclaimed, with a Retry-After header and ambiguous). Unless the error explicitly says nothing was sent (for example ambiguous: false), treat any write as possibly applied; list or read the state of what you changed before retrying a write; never re-create (e.g. a group) without reading/listing first; reads can be retried after a short back-off. Honor Retry-After when present.

Warming

  • GET/v1/sessions/{name}/warming

    Read this channel's warming state

    Parameters

    name (path, required)
    Channel ID.

    Responses

    200
    OK
    400
    The request was refused as sent.
    401
    Missing, invalid or stale token, or a channel this token does not open.
    403
    The token is valid and may not do this.
    404
    The route or the named object does not exist.
    409
    The channel's state does not allow this, for example not_linked or stood_down.
    429
    A gateway flood guard or the webhook-test cooldown (rate_limited, with a Retry-After header), the gateway being busy with this channel's earlier requests (gateway_busy, Retry-After: 1), a sandbox channel's allowance (sandbox_allowance_exceeded, with Retry-After), an operator stop (daily_send_cap_exceeded), an optional warm-up protection allowance (daily_cap_<class>, only when warm-up protection is on), a history request inside its rate limit (history_request_too_soon, with Retry-After), or WhatsApp throttling the number (whatsapp_rate_limited, no Retry-After). Paid numbers have no gateway allowance. code says which: the bodies never share one.
    500
    The gateway could not complete the request.
    502
    The service behind the gateway could not be reached or answered unusably. Retry.
    503
    Temporarily unavailable, for example the token could not be checked, the gateway could not confirm its own account setup (operator_unresolved, with a Retry-After header), or a call made under a phone lane reached the lane's deadline (lane_reclaimed, with a Retry-After header and ambiguous). Unless the error explicitly says nothing was sent (for example ambiguous: false), treat any write as possibly applied; list or read the state of what you changed before retrying a write; never re-create (e.g. a group) without reading/listing first; reads can be retried after a short back-off. Honor Retry-After when present.

  • PUT/v1/sessions/{name}/warming

    Turn warming on or off for this channel

    Parameters

    name (path, required)
    Channel ID.

    Request body

    enabled (boolean, required)
    restart_ack (boolean)
    Confirms a restart after a safety stop.
    acknowledge (object)

    Responses

    200
    OK
    400
    The request was refused as sent.
    401
    Missing, invalid or stale token, or a channel this token does not open.
    403
    The token is valid and may not do this.
    404
    The route or the named object does not exist.
    409
    The channel's state does not allow this, for example not_linked or stood_down.
    429
    A gateway flood guard or the webhook-test cooldown (rate_limited, with a Retry-After header), the gateway being busy with this channel's earlier requests (gateway_busy, Retry-After: 1), a sandbox channel's allowance (sandbox_allowance_exceeded, with Retry-After), an operator stop (daily_send_cap_exceeded), an optional warm-up protection allowance (daily_cap_<class>, only when warm-up protection is on), a history request inside its rate limit (history_request_too_soon, with Retry-After), or WhatsApp throttling the number (whatsapp_rate_limited, no Retry-After). Paid numbers have no gateway allowance. code says which: the bodies never share one.
    500
    The gateway could not complete the request.
    502
    The service behind the gateway could not be reached or answered unusably. Retry.
    503
    Temporarily unavailable, for example the token could not be checked, the gateway could not confirm its own account setup (operator_unresolved, with a Retry-After header), or a call made under a phone lane reached the lane's deadline (lane_reclaimed, with a Retry-After header and ambiguous). Unless the error explicitly says nothing was sent (for example ambiguous: false), treat any write as possibly applied; list or read the state of what you changed before retrying a write; never re-create (e.g. a group) without reading/listing first; reads can be retried after a short back-off. Honor Retry-After when present.

  • PUT/v1/sessions/{name}/warming/webhooks

    Choose whether this channel's receivers get warming traffic

    Parameters

    name (path, required)
    Channel ID.

    Request body

    include_warming (boolean, required)

    Responses

    200
    OK
    400
    The request was refused as sent.
    401
    Missing, invalid or stale token, or a channel this token does not open.
    403
    The token is valid and may not do this.
    404
    The route or the named object does not exist.
    409
    The channel's state does not allow this, for example not_linked or stood_down.
    429
    A gateway flood guard or the webhook-test cooldown (rate_limited, with a Retry-After header), the gateway being busy with this channel's earlier requests (gateway_busy, Retry-After: 1), a sandbox channel's allowance (sandbox_allowance_exceeded, with Retry-After), an operator stop (daily_send_cap_exceeded), an optional warm-up protection allowance (daily_cap_<class>, only when warm-up protection is on), a history request inside its rate limit (history_request_too_soon, with Retry-After), or WhatsApp throttling the number (whatsapp_rate_limited, no Retry-After). Paid numbers have no gateway allowance. code says which: the bodies never share one.
    500
    The gateway could not complete the request.
    502
    The service behind the gateway could not be reached or answered unusably. Retry.
    503
    Temporarily unavailable, for example the token could not be checked, the gateway could not confirm its own account setup (operator_unresolved, with a Retry-After header), or a call made under a phone lane reached the lane's deadline (lane_reclaimed, with a Retry-After header and ambiguous). Unless the error explicitly says nothing was sent (for example ambiguous: false), treat any write as possibly applied; list or read the state of what you changed before retrying a write; never re-create (e.g. a group) without reading/listing first; reads can be retried after a short back-off. Honor Retry-After when present.
API reference · HelloHop docs