openapi: 3.1.0 info: title: SMS-Docs JSON API version: 1.0.0 description: >- Machine-readable contract for the SMS-Docs JSON API. Every request is a POST with `Content-Type: application/json` and the same envelope: `auth` carries the API key, `data` carries one or more operation objects. The operation is chosen by `data[].type`. This document covers the JSON transport only, and within it only the publicly documented operations. XML, HTTP and SOAP transports are described in the documentation pages, not here. contact: url: https://sms-doc.pages.dev/ servers: - url: https://alphasms.net description: Synchronous API tags: - name: JSON API description: Single-endpoint JSON transport paths: /api/json.php: post: operationId: jsonApiSync summary: Send a synchronous JSON API request description: >- One endpoint for every operation. The operation is selected by `data[].type`. Several operations may be sent in one request — `data` is an array. The response returns `msg_id` per message immediately. tags: - JSON API security: - ApiKey: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/Request' responses: '200': description: >- Always 200, including on failure. Check `success` at the top level, then `success` inside each `data[]` item. content: application/json: schema: $ref: '#/components/schemas/Response' webhooks: messageStatus: post: operationId: messageStatusWebhook summary: Delivery status callback security: [] description: >- Sent to the URL given in the `hook` field of a send operation, once the message reaches a final state. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/StatusWebhook' responses: '200': description: Acknowledged. components: securitySchemes: ApiKey: type: apiKey in: header name: auth description: >- The API key is NOT sent as a header. It is the `auth` field of the request body. This scheme is declared so tools show the key as a credential; put the value into `auth`. schemas: Request: type: object required: - auth - data properties: auth: type: string description: API key from the personal cabinet. example: bb56a4369eb19***cfec6d1776bd25 data: type: array minItems: 1 description: One or more operation objects. items: $ref: '#/components/schemas/Operation' Operation: oneOf: - $ref: '#/components/schemas/OpBalance' - $ref: '#/components/schemas/OpCallOtp' - $ref: '#/components/schemas/OpHlr' - $ref: '#/components/schemas/OpPipeline' - $ref: '#/components/schemas/OpRcs' - $ref: '#/components/schemas/OpRcsSms' - $ref: '#/components/schemas/OpRcsViberSms' - $ref: '#/components/schemas/OpSender' - $ref: '#/components/schemas/OpSms' - $ref: '#/components/schemas/OpStatus' - $ref: '#/components/schemas/OpTelegram' - $ref: '#/components/schemas/OpTemplateCreate' - $ref: '#/components/schemas/OpTemplateDelete' - $ref: '#/components/schemas/OpTemplateList' - $ref: '#/components/schemas/OpTemplateViberCreate' - $ref: '#/components/schemas/OpTemplateViberDelete' - $ref: '#/components/schemas/OpTemplateViberList' - $ref: '#/components/schemas/OpTemplateWhatsappList' - $ref: '#/components/schemas/OpViber' - $ref: '#/components/schemas/OpViberSms' - $ref: '#/components/schemas/OpVoice' - $ref: '#/components/schemas/OpWhatsapp' - $ref: '#/components/schemas/OpWhatsappSms' discriminator: propertyName: type mapping: balance: '#/components/schemas/OpBalance' call/otp: '#/components/schemas/OpCallOtp' hlr: '#/components/schemas/OpHlr' pipeline: '#/components/schemas/OpPipeline' rcs: '#/components/schemas/OpRcs' rcs+sms: '#/components/schemas/OpRcsSms' rcs+viber+sms: '#/components/schemas/OpRcsViberSms' sender: '#/components/schemas/OpSender' sms: '#/components/schemas/OpSms' status: '#/components/schemas/OpStatus' telegram: '#/components/schemas/OpTelegram' template/create: '#/components/schemas/OpTemplateCreate' template/delete: '#/components/schemas/OpTemplateDelete' template/list: '#/components/schemas/OpTemplateList' template/viber/create: '#/components/schemas/OpTemplateViberCreate' template/viber/delete: '#/components/schemas/OpTemplateViberDelete' template/viber/list: '#/components/schemas/OpTemplateViberList' template/whatsapp/list: '#/components/schemas/OpTemplateWhatsappList' viber: '#/components/schemas/OpViber' viber+sms: '#/components/schemas/OpViberSms' voice: '#/components/schemas/OpVoice' whatsapp: '#/components/schemas/OpWhatsapp' whatsapp+sms: '#/components/schemas/OpWhatsappSms' Response: type: object properties: success: type: boolean description: >- Whether the envelope itself was accepted. Note: this is a boolean, even though some documentation tables call it an integer. error: type: string description: Present when the envelope was rejected, e.g. `Access denied`. data: type: array description: One result per operation sent, in the same order. items: $ref: '#/components/schemas/ResponseItem' ResponseItem: type: object properties: success: type: boolean description: Result of this single operation. error: type: string description: Present when this operation failed. data: type: - object - array description: >- Operation payload. Shape depends on the operation type: an object for most operations, a list for template/whatsapp/list. items: type: object additionalProperties: true properties: id: type: - string - number description: Your own message identifier. msg_id: type: - string - number description: Identifier assigned by the gateway. parts: type: number description: Number of message parts billed. AsyncResponse: type: object properties: success: type: boolean request_id: type: string description: Identifier of the queued request; repeated in the webhook. example: cf-ray-1234567890-ABC StatusWebhook: type: object required: - success properties: id: type: string description: Your own message identifier. msg_id: type: string description: Identifier assigned by the gateway. type: type: string enum: - sms - viber - voice - rcs - whatsapp status: type: string description: Message status. success: type: boolean description: True when the message was delivered or read. error: type: string description: Reason the message was rejected. updated: type: string format: date-time reply: type: string description: Digit entered by the recipient (DTMF). duration: type: number description: Call duration in seconds. request_id: type: string description: Matches the async response. replies: type: array description: Replies to the message (Viber 2 Way and WhatsApp). items: type: object properties: datetime: type: string format: date-time message: type: string type: type: string description: 'WhatsApp: type of the reply (text, image, location, button…).' button: type: string description: 'WhatsApp: the button the subscriber pressed.' location: type: object description: 'WhatsApp: the location the subscriber sent.' properties: latitude: type: number longitude: type: number name: type: string address: type: string media: type: object properties: url: type: string format: uri filename: type: string description: Viber only. filesize: type: number description: Viber only. type: type: string description: 'WhatsApp: MIME type of the file.' OpBalance: type: object title: Get the current balance of the user's account description: Documented at docs/api/json/balance.md properties: type: description: Request type enum: - balance example: balance type: string required: - type additionalProperties: true OpCallOtp: type: object title: >- Voice OTP: places a call to the subscriber from a number whose last 4 digits are the one-time code; returns the code and the fee. description: Documented at docs/api/json/voice/otp.md properties: type: description: Request type enum: - call/otp example: call/otp type: string id: description: Unique message identifier in the client system example: 100500 type: number phone: description: Phone number to be checked example: 447700900123 type: number required: - id - phone - type additionalProperties: true OpHlr: type: object title: >- HLR lookup: check number validity and get operator/porting details without notifying the subscriber description: Documented at docs/api/json/hlr.md properties: type: description: Request type enum: - hlr example: hlr type: string id: description: Unique message identifier in the client system example: 100500 type: number phone: description: Phone number of the recipient of the message example: 447700900123 type: number required: - id - phone - type additionalProperties: true OpPipeline: type: object title: >- Multi-channel delivery: one request, several channels tried in the order given in `pipeline` (voice, telegram, viber, rcs, sms, whatsapp). Telegram only for OTP, voice recommended only for OTP; SMS/Viber for OTP and transactional. The `whatsapp` stage sends free-form text only, which WhatsApp delivers within 24 hours after the subscriber's last message; templates, files and codes go with `type`: `whatsapp`. description: Documented at docs/api/json/multi_channel.md properties: type: description: Request type enum: - pipeline example: pipeline type: string hook: description: >- URL address of the script where the message delivery status will be sent. The gateway does not store `hook` for type `pipeline` — the status goes to the notification address from API settings; on the async API `hook` still receives a refusal webhook with status REJECTED example: https://example.org/webhook/url.php type: string id: description: Unique message identifier in the client system example: 100500 type: number phone: description: Phone number of the recipient of the messages. Digits only, without `+` example: 447700900123 type: number pipeline: description: >- Sequence of use of communication channels / channels in the order they are tried; values may not repeat type: array rcs: description: >- NOT IN THE PARAMETERS TABLE — present only in the multi_channel.md request example as {"signature": "SenderID", "message": "Your code is 1234"}, with "rcs" listed in the pipeline array. No documented requiredness, no documented sub-field table type: object sms: description: SMS message parameters properties: message: description: Message text to be sent via SMS example: Your code is 100500 type: string signature: description: Signature in the message example: SenderID type: string required: - message - signature type: object telegram: description: Telegram message parameters properties: message: description: Message text to be sent via Telegram example: '100500' type: string required: - message type: object viber: description: Viber message parameters properties: message: description: Message text to be sent via Viber example: Your code is 100500 type: string signature: description: Signature in the message example: SenderID type: string type: description: Viber message type example: text type: string required: - message - signature - type type: object voice: description: Voice message options properties: gender: description: Voice type (male or female) enum: - male - female example: female type: string language: description: Voice language example: en-GB type: string name: description: Language model name example: en-GB-Standard-A type: string required: - gender - language - name type: object whatsapp: description: >- Parameters of the WhatsApp stage: free-form text, delivered only within 24 hours after the subscriber's last message properties: message: description: Message text to be sent via WhatsApp example: Your code is 1234 type: string signature: description: Sender name connected to WhatsApp example: SenderID type: string required: - message - signature type: object required: - id - phone - pipeline - sms - telegram - type - viber - voice - whatsapp additionalProperties: true OpRcs: type: object title: Send an RCS message with text, image and a button leading to the given link. description: Documented at docs/api/json/rcs/send.md properties: type: description: Request type enum: - rcs example: rcs type: string hook: description: URL address of the script where the message delivery status will be sent example: https://example.org/webhook/url.php type: string id: description: Unique message identifier in the client system example: 100500 type: number phone: description: Phone number of the recipient of the message example: 447700900123 type: number rcs_button: description: Caption to be displayed on the button example: Button caption type: string rcs_image: description: Link to the image to be sent in the message example: https://url.com/storage/images/image.png type: string rcs_lifetime: description: >- RCS message lifetime in seconds. Minimum value: 60 seconds. Default: 2 days (172800 seconds) example: 172800 type: number rcs_link: description: Link that will be followed after pressing the button example: https://redirect.url type: string rcs_message: description: >- Message text to be sent via SMS (verbatim from the table — copy-paste artefact; the example calls it "Message text to be sent via RCS") example: Message text to be sent via RCS type: string rcs_signature: description: Signature in the message example: RCSTest type: string short_link: description: Shorter and track links (according to the tariff) example: true type: boolean required: - id - phone - rcs_button - rcs_image - rcs_link - rcs_message - rcs_signature - type additionalProperties: true OpRcsSms: type: object title: >- Send an RCS message (text, image, button) with automatic resending by SMS if RCS delivery fails. description: Documented at docs/api/json/rcs/resending_sms.md properties: type: description: Request type enum: - rcs+sms example: rcs+sms type: string hook: description: URL address of the script where the message delivery status will be sent example: https://example.org/webhook/url.php type: string id: description: Unique message identifier in the client system example: 100500 type: number phone: description: Phone number of the recipient of the message example: 447700900123 type: number rcs_button: description: Caption to be displayed on the button example: Button caption type: string rcs_image: description: Link to the image to be sent in the message example: https://url.com/storage/images/image.png type: string rcs_lifetime: description: >- RCS message lifetime in seconds. Minimum value: 60 seconds. Default: 2 days (172800 seconds) example: 172800 type: number rcs_link: description: Link that will be followed after pressing the button example: https://redirect.url type: string rcs_message: description: >- Message text to be sent via SMS (verbatim from the table — copy-paste artefact; the example calls it "Message text to be sent via RCS") example: Message text to be sent via RCS type: string rcs_signature: description: Signature in the message example: RCSTest type: string short_link: description: Shorter and track links (according to the tariff) example: true type: boolean sms_message: description: Message text to be sent via SMS example: Message text to be sent via SMS type: string sms_signature: description: Signature in the message example: SMSTest type: string required: - id - phone - rcs_button - rcs_image - rcs_link - rcs_message - rcs_signature - sms_message - sms_signature - type additionalProperties: true OpRcsViberSms: type: object title: >- Send an RCS message (text, image, button) with fallback resending by Viber and then SMS if delivery fails. description: Documented at docs/api/json/rcs/resending_viber.md properties: type: description: Request type enum: - rcs+viber+sms example: rcs+viber+sms type: string hook: description: URL address of the script where the message delivery status will be sent example: https://example.org/webhook/url.php type: string id: description: Unique message identifier in the client system example: 100500 type: number phone: description: Phone number of the recipient of the message example: 447700900123 type: number rcs_button: description: Caption to be displayed on the button example: Button caption type: string rcs_image: description: Link to the image to be sent in the message example: https://url.com/storage/images/image.png type: string rcs_lifetime: description: >- RCS message lifetime in seconds. Minimum value: 60 seconds. Default: 2 days (172800 seconds) example: 172800 type: number rcs_link: description: Link that will be followed after pressing the button example: https://redirect.url type: string rcs_message: description: >- Message text to be sent via SMS (verbatim from the table — copy-paste artefact; the example calls it "Message text to be sent via RCS") example: Message text to be sent via RCS type: string rcs_signature: description: Signature in the message example: RCSTest type: string short_link: description: Shorter and track links (according to the tariff) example: true type: boolean sms_message: description: Message text to be sent via SMS example: Message text to be sent via SMS type: string sms_signature: description: Signature in the message example: SMSTest type: string viber_button: description: Caption to be displayed on the button example: Button caption type: string viber_image: description: Link to the image to be sent in the message example: https://url.com/storage/images/image.png type: string viber_link: description: Link that will be followed after pressing the button example: https://redirect.url type: string viber_message: description: Message text to be sent via Viber example: Message text to send via Viber type: string viber_signature: description: Signature in the message example: ViberTest type: string viber_type: description: Viber message type example: text+image+link type: string required: - id - phone - rcs_button - rcs_image - rcs_link - rcs_message - rcs_signature - sms_message - sms_signature - type - viber_signature - viber_type additionalProperties: true oneOf: - title: 'rcs+viber+sms — viber_type: carousel' properties: viber_type: const: carousel required: - viber_carousel - viber_message - viber_type - title: 'rcs+viber+sms — viber_type: image' properties: viber_type: const: image required: - viber_image - viber_type - title: 'rcs+viber+sms — viber_type: text' properties: viber_type: const: text required: - viber_message - viber_type - title: 'rcs+viber+sms — viber_type: text+image+link' properties: viber_type: const: text+image+link required: - viber_button - viber_image - viber_link - viber_message - viber_type - title: 'rcs+viber+sms — viber_type: text+link' properties: viber_type: const: text+link required: - viber_button - viber_link - viber_message - viber_type OpSender: type: object title: Get the list of senders (alpha-names) available for sending messages description: Documented at docs/api/json/sender.md properties: type: description: Request type enum: - sender example: sender type: string required: - type additionalProperties: true OpSms: type: object title: Send an SMS message to a phone number description: Documented at docs/api/json/send_sms.md properties: type: description: Request type enum: - sms example: sms type: string hook: description: URL address of the script where the message delivery status will be sent example: https://example.org/webhook/url.php type: string id: description: Unique message identifier in the client system example: 100500 type: number phone: description: Phone number of the recipient of the message example: 447700900123 type: number short_link: description: Shorter and track links (according to the tariff) example: true type: boolean sms_lifetime: description: >- SMS message lifetime in seconds; min. value 1 hour (3600 seconds), max. value 3 days (259200 seconds), default 2 days (172800 seconds) example: 172800 type: number sms_message: description: Message text to be sent via SMS example: Message text to be sent via SMS type: string sms_signature: description: Signature in the message example: SMSTest type: string unsubscribe_link: description: Customers can unsubscribe by clicking the link (according to the tariff) example: true type: boolean required: - id - phone - sms_message - sms_signature - type additionalProperties: true OpStatus: type: object title: Get the current status of a previously sent message description: Documented at docs/api/json/message_status.md properties: type: description: Request type enum: - status example: status type: string id: description: Unique message identifier in the client system example: 100500 type: number required: - id - type additionalProperties: true OpTelegram: type: object title: Send a one-time password (OTP) via Telegram. description: Documented at docs/api/json/telegram/otp.md properties: type: description: Request type enum: - telegram example: telegram type: string hook: description: URL address of the script where the message delivery status will be sent example: https://example.org/webhook/url.php type: string id: description: Unique message identifier in the client system example: 100500 type: number message: description: Message with one-time password. Contains from 4 to 8 digits example: '123456' type: string phone: description: Phone number of the recipient of the message example: 447700900123 type: number telegram_lifetime: description: >- Telegram message lifetime in seconds. Minimum value: 60 seconds. Default: 2 days (172800 seconds) example: 172800 type: number required: - id - message - phone - type additionalProperties: true OpTemplateCreate: type: object title: Creates a new SMS message template and returns its id, text, name and character/parts count. description: Documented at docs/api/json/template/create.md properties: type: description: Request type enum: - template/create example: template/create type: string name: description: Template name example: First type: string template: description: Template text example: New template text type: string required: - template - type additionalProperties: true OpTemplateDelete: type: object title: >- Deletes SMS template(s) by identifier and/or by exact template text; returns the number of deleted templates. description: Documented at docs/api/json/template/delete.md properties: type: description: Request type enum: - template/delete example: template/delete type: string id: description: Message Template identifier example: '1' type: string template: description: Message Template Text example: Template text type: string required: - type additionalProperties: true OpTemplateList: type: object title: >- Returns the list of the client's SMS templates with id, name, text, character/parts count and creation timestamp. description: Documented at docs/api/json/template/list.md properties: type: description: Request type enum: - template/list example: template/list type: string required: - type additionalProperties: true OpTemplateViberCreate: type: object title: >- Creates a new Viber message template (text plus sender signature) and returns its id and moderation status. description: Documented at docs/api/json/template/viber/create.md properties: type: description: Request type enum: - template/viber/create example: template/viber/create type: string signature: description: Signature in the message example: ViberTest type: string template: description: >- Request type (verbatim from the docs — evidently a copy-paste error; the field carries the template text) example: New template text type: string required: - template - type additionalProperties: true OpTemplateViberDelete: type: object title: >- Deletes Viber template(s) by identifier and/or by exact template text; returns the number of deleted templates. description: Documented at docs/api/json/template/viber/delete.md properties: type: description: Request type enum: - template/viber/delete example: template/viber/delete type: string id: description: Message Template identifier example: 1 type: integer template: description: >- Request type (verbatim from the docs — evidently a copy-paste error; the field carries the template text) example: Template text type: string required: - type additionalProperties: true OpTemplateViberList: type: object title: >- Returns the list of the client's Viber templates with id, text, signature and moderation status. description: Documented at docs/api/json/template/viber/list.md properties: type: description: Request type enum: - template/viber/list example: template/viber/list type: string required: - type additionalProperties: true OpTemplateWhatsappList: type: object title: >- Returns the approved WhatsApp templates with the number of values (`params`) and what each needs at send time (`shape`). description: Documented at docs/api/json/whatsapp/templates.md properties: type: description: Request type enum: - template/whatsapp/list example: template/whatsapp/list type: string signature: description: 'Sender name: only its templates. Without it the templates of all senders are returned' type: string example: WhatsAppTest required: - type additionalProperties: true OpViber: type: object title: >- Отправка Viber-сообщения. Одна операция data[].type="viber", пять разновидностей задаются полем viber_type: text, image, text+link, text+image+link, carousel — каждой посвящена своя страница доки; набор viber_*-полей и их обязательность зависят от viber_type. description: >- Documented at docs/api/json/viber/text.md, docs/api/json/viber/image.md, docs/api/json/viber/text_link.md, docs/api/json/viber/text_link_image.md, docs/api/json/viber/carousel.md properties: type: description: Request type enum: - viber example: viber type: string hook: description: URL address of the script where the message delivery status will be sent example: https://example.org/webhook/url.php type: string id: description: Unique message identifier in the client system example: 100500 type: number phone: description: Phone number of the recipient of the message example: 447700900123 type: number short_link: description: Shorter and track links (according to the tariff) example: true type: boolean viber_button: description: >- Caption to be displayed on the button — в таблице помечено required на страницах viber_type=text+link и text+image+link; на остальных страницах поля нет example: Button caption type: string viber_carousel: description: >- List of objects with parameters for carousel slides (2-5 slides) — в таблице помечено required только на странице viber_type=carousel; на остальных страницах поля нет items: properties: button: description: Caption to be displayed on the slide button example: Button caption type: string button2: description: Caption to be displayed on the slide additional button type: string caption: description: Carousel slide caption to be sent via Viber example: Title 1 type: string image: description: Link to the image to be sent in the message example: https://url.com/storage/images/image1.png type: string url: description: Link that will be followed after pressing the slide button example: https://example.org type: string url2: description: Link that will be followed after pressing the slide additional button type: string required: - button - caption - image - url type: object type: array viber_image: description: >- Link to the image to be sent in the message — в таблице помечено required на страницах viber_type=image и text+image+link; на остальных страницах поля нет example: https://url.com/storage/images/image.png type: string viber_lifetime: description: >- Viber message lifetime in seconds. Min. value: 60 seconds. Default: 1 day (86400 seconds) example: 86400 type: number viber_link: description: >- Link that will be followed after pressing the button — в таблице помечено required на страницах viber_type=text+link и text+image+link; на остальных страницах поля нет example: https://redirect.url type: string viber_message: description: >- Message text to be sent via Viber — в таблице помечено required на страницах viber_type=text, text+link, text+image+link, carousel; на странице viber_type=image поля нет вовсе example: Message text to send via Viber type: string viber_signature: description: Signature in the message example: ViberTest type: string viber_type: description: Viber message type enum: - text - image - text+link - text+image+link - carousel example: text type: string required: - id - phone - type - viber_signature - viber_type additionalProperties: true oneOf: - title: 'viber — viber_type: carousel' properties: viber_type: const: carousel required: - viber_carousel - viber_message - viber_type - title: 'viber — viber_type: image' properties: viber_type: const: image required: - viber_image - viber_type - title: 'viber — viber_type: text' properties: viber_type: const: text required: - viber_message - viber_type - title: 'viber — viber_type: text+image+link' properties: viber_type: const: text+image+link required: - viber_button - viber_image - viber_link - viber_message - viber_type - title: 'viber — viber_type: text+link' properties: viber_type: const: text+link required: - viber_button - viber_link - viber_message - viber_type OpViberSms: type: object title: >- Отправка Viber-сообщения с автоматической переотправкой по SMS, если Viber не доставлен. Один объект data[] несёт и viber_*-, и sms_*-поля. description: Documented at docs/api/json/viber/resending_sms.md properties: type: description: Request type enum: - viber+sms example: viber+sms type: string hook: description: URL address of the script where the message delivery status will be sent example: https://example.org/webhook/url.php type: string id: description: Unique message identifier in the client system example: 100500 type: number phone: description: Phone number of the recipient of the message example: 447700900123 type: number short_link: description: Shorter and track links (according to the tariff) example: true type: boolean sms_message: description: Message text to be sent via SMS example: Message text to be sent via SMS type: string sms_signature: description: Signature in the message example: SMSTest type: string viber_button: description: Caption to be displayed on the button example: Button caption type: string viber_image: description: Link to the image to be sent in the message example: https://url.com/storage/images/image.png type: string viber_lifetime: description: >- Viber message lifetime in seconds. Min. value: 60 seconds. Default: 1 day (86400 seconds) example: 86400 type: number viber_link: description: Link that will be followed after pressing the button example: https://redirect.url type: string viber_message: description: Message text to be sent via Viber example: Message text to send via Viber type: string viber_signature: description: Signature in the message example: ViberTest type: string viber_type: description: Viber message type enum: - text+image+link example: text+image+link type: string required: - id - phone - sms_message - sms_signature - type - viber_signature - viber_type additionalProperties: true oneOf: - title: 'viber+sms — viber_type: carousel' properties: viber_type: const: carousel required: - viber_carousel - viber_message - viber_type - title: 'viber+sms — viber_type: image' properties: viber_type: const: image required: - viber_image - viber_type - title: 'viber+sms — viber_type: text' properties: viber_type: const: text required: - viber_message - viber_type - title: 'viber+sms — viber_type: text+image+link' properties: viber_type: const: text+image+link required: - viber_button - viber_image - viber_link - viber_message - viber_type - title: 'viber+sms — viber_type: text+link' properties: viber_type: const: text+link required: - viber_button - viber_link - viber_message - viber_type OpVoice: type: object title: >- Voice call: text-to-speech a message to a phone number, with voice model selection and optional DTMF tone collection. description: Documented at docs/api/json/voice/call.md properties: type: description: Request type enum: - voice example: voice type: string dtmf: description: Tone set (DTMF) usage flag example: false type: boolean id: description: Unique message identifier in the client system example: 100500 type: number message: description: The text of the message to be voiced example: Your code is 100500 type: string phone: description: Phone number to be checked example: 447700900123 type: number voice: description: Voice parameters properties: gender: description: Voice type (male or female) enum: - male - female example: female type: string language: description: Voice language example: en-GB type: string name: description: Language model name example: en-GB-Standard-A type: string required: - gender - language - name type: object required: - dtmf - id - message - phone - type - voice additionalProperties: true OpWhatsapp: type: object title: >- WhatsApp message: an approved template (with a file, location or text header, button values, a coupon or a one-time code) at any time, or a free-form message (text, file, location, card with a button) within 24 hours after the subscriber's last message. Either whatsapp_template or free-form content (whatsapp_message, a file or whatsapp_location) is required. description: Documented at docs/api/json/whatsapp/send.md, docs/api/json/whatsapp/otp.md properties: type: description: Request type enum: - whatsapp example: whatsapp type: string hook: description: URL address of the script where the message delivery status will be sent type: string example: https://example.org/webhook/url.php id: description: Unique message identifier in the client system type: number example: 100500 phone: description: Phone number of the recipient, digits only, in international format type: number example: 447700900123 whatsapp_audio: description: Link to an audio file, free-form messages only type: string whatsapp_button: description: 'Free-form card: the caption of the button. Works only together with whatsapp_link' type: string maxLength: 20 whatsapp_button_var: description: End of the link of the template button with {{1}} type: string example: spring-24 maxLength: 2000 whatsapp_code: description: One-time code of an authentication template; fills the text and the copy button type: string example: '481516' maxLength: 15 whatsapp_coupon: description: Coupon code for the copy-code button of the template type: string example: SPRING15 maxLength: 15 whatsapp_document: description: 'Link to a document: the document header of the template or a free-form file' type: string whatsapp_filename: description: File name the recipient sees for a document type: string example: Invoice A-1024.pdf maxLength: 240 whatsapp_header: description: Value of {{1}} in a text header of the template type: string maxLength: 60 whatsapp_image: description: 'Link to an image: the image header of the template or a free-form photo' type: string example: https://url.com/storage/images/order.png whatsapp_language: description: Template language code; without it the approved language of the template is used type: string example: en whatsapp_lifetime: description: How long to try to deliver the message, in seconds type: integer example: 86400 minimum: 60 maximum: 86400 whatsapp_link: description: >- Free-form card: the link of the button. Works only together with whatsapp_button: one without the other is ignored and the text goes out as usual type: string whatsapp_location: description: 'Location: the location header of the template or a free-form location message' type: object properties: latitude: description: Latitude type: number minimum: -90 maximum: 90 longitude: description: Longitude type: number minimum: -180 maximum: 180 name: description: Name of the place type: string address: description: Address type: string required: - latitude - longitude whatsapp_message: description: >- Free-form text up to 4096 characters, delivered only within the 24-hour window. With a file it becomes the caption, up to 1024 characters type: string example: Your invoice for September maxLength: 4096 whatsapp_preview_url: description: Show a preview of the first link of a free-form text type: boolean example: false whatsapp_signature: description: Sender name connected to WhatsApp in the account type: string example: WhatsAppTest whatsapp_template: description: >- Name of an approved template ([a-z0-9_]). Required outside the 24-hour window; without it the message is free-form type: string example: order_ready pattern: ^[a-z0-9_]{1,512}$ whatsapp_var: description: 'Template values in order: {{1}}, {{2}}… Their number must equal `params` of the template' type: array items: type: string maxLength: 1024 whatsapp_video: description: 'Link to a video: the video header of the template or a free-form video' type: string required: - id - phone - type - whatsapp_signature additionalProperties: true anyOf: - required: - whatsapp_template - required: - whatsapp_message - required: - whatsapp_image - required: - whatsapp_video - required: - whatsapp_audio - required: - whatsapp_document - required: - whatsapp_location allOf: - if: anyOf: - required: - whatsapp_image - required: - whatsapp_video - required: - whatsapp_document then: properties: whatsapp_message: maxLength: 1024 - not: anyOf: - required: - whatsapp_image - whatsapp_video - required: - whatsapp_image - whatsapp_audio - required: - whatsapp_image - whatsapp_document - required: - whatsapp_video - whatsapp_audio - required: - whatsapp_video - whatsapp_document - required: - whatsapp_audio - whatsapp_document - if: not: required: - whatsapp_template then: allOf: - not: allOf: - anyOf: - required: - whatsapp_image - required: - whatsapp_video - required: - whatsapp_audio - required: - whatsapp_document - required: - whatsapp_location - not: allOf: - required: - whatsapp_link - whatsapp_button - anyOf: - required: - whatsapp_image - required: - whatsapp_video - required: - whatsapp_audio - required: - whatsapp_document - required: - whatsapp_location - not: required: - whatsapp_location - whatsapp_message - not: required: - whatsapp_audio - whatsapp_message - if: required: - whatsapp_template then: allOf: - not: required: - whatsapp_audio - not: allOf: - anyOf: - required: - whatsapp_image - required: - whatsapp_video - required: - whatsapp_audio - required: - whatsapp_document - required: - whatsapp_location - not: allOf: - anyOf: - required: - whatsapp_image - required: - whatsapp_video - required: - whatsapp_audio - required: - whatsapp_document - required: - whatsapp_location - required: - whatsapp_header - if: required: - whatsapp_code then: required: - whatsapp_template OpWhatsappSms: type: object title: >- The same WhatsApp message with an SMS fallback: when WhatsApp is not delivered, the SMS goes out. description: Documented at docs/api/json/whatsapp/send.md, docs/api/json/whatsapp/otp.md properties: type: description: Request type enum: - whatsapp+sms example: whatsapp+sms type: string hook: description: URL address of the script where the message delivery status will be sent type: string example: https://example.org/webhook/url.php id: description: Unique message identifier in the client system type: number example: 100500 phone: description: Phone number of the recipient, digits only, in international format type: number example: 447700900123 sms_lifetime: description: Lifetime of the fallback SMS in seconds type: number example: 172800 sms_message: description: SMS text for the fallback type: string example: Anna, your order A-1024 is ready sms_signature: description: SMS sender name for the fallback type: string example: SMSTest whatsapp_audio: description: Link to an audio file, free-form messages only type: string whatsapp_button: description: 'Free-form card: the caption of the button. Works only together with whatsapp_link' type: string maxLength: 20 whatsapp_button_var: description: End of the link of the template button with {{1}} type: string example: spring-24 maxLength: 2000 whatsapp_code: description: One-time code of an authentication template; fills the text and the copy button type: string example: '481516' maxLength: 15 whatsapp_coupon: description: Coupon code for the copy-code button of the template type: string example: SPRING15 maxLength: 15 whatsapp_document: description: 'Link to a document: the document header of the template or a free-form file' type: string whatsapp_filename: description: File name the recipient sees for a document type: string example: Invoice A-1024.pdf maxLength: 240 whatsapp_header: description: Value of {{1}} in a text header of the template type: string maxLength: 60 whatsapp_image: description: 'Link to an image: the image header of the template or a free-form photo' type: string example: https://url.com/storage/images/order.png whatsapp_language: description: Template language code; without it the approved language of the template is used type: string example: en whatsapp_lifetime: description: How long to try to deliver the message, in seconds type: integer example: 86400 minimum: 60 maximum: 86400 whatsapp_link: description: >- Free-form card: the link of the button. Works only together with whatsapp_button: one without the other is ignored and the text goes out as usual type: string whatsapp_location: description: 'Location: the location header of the template or a free-form location message' type: object properties: latitude: description: Latitude type: number minimum: -90 maximum: 90 longitude: description: Longitude type: number minimum: -180 maximum: 180 name: description: Name of the place type: string address: description: Address type: string required: - latitude - longitude whatsapp_message: description: >- Free-form text up to 4096 characters, delivered only within the 24-hour window. With a file it becomes the caption, up to 1024 characters type: string example: Your invoice for September maxLength: 4096 whatsapp_preview_url: description: Show a preview of the first link of a free-form text type: boolean example: false whatsapp_signature: description: Sender name connected to WhatsApp in the account type: string example: WhatsAppTest whatsapp_template: description: >- Name of an approved template ([a-z0-9_]). Required outside the 24-hour window; without it the message is free-form type: string example: order_ready pattern: ^[a-z0-9_]{1,512}$ whatsapp_var: description: 'Template values in order: {{1}}, {{2}}… Their number must equal `params` of the template' type: array items: type: string maxLength: 1024 whatsapp_video: description: 'Link to a video: the video header of the template or a free-form video' type: string required: - id - phone - sms_message - sms_signature - type - whatsapp_signature additionalProperties: true anyOf: - required: - whatsapp_template - required: - whatsapp_message - required: - whatsapp_image - required: - whatsapp_video - required: - whatsapp_audio - required: - whatsapp_document - required: - whatsapp_location allOf: - if: anyOf: - required: - whatsapp_image - required: - whatsapp_video - required: - whatsapp_document then: properties: whatsapp_message: maxLength: 1024 - not: anyOf: - required: - whatsapp_image - whatsapp_video - required: - whatsapp_image - whatsapp_audio - required: - whatsapp_image - whatsapp_document - required: - whatsapp_video - whatsapp_audio - required: - whatsapp_video - whatsapp_document - required: - whatsapp_audio - whatsapp_document - if: not: required: - whatsapp_template then: allOf: - not: allOf: - anyOf: - required: - whatsapp_image - required: - whatsapp_video - required: - whatsapp_audio - required: - whatsapp_document - required: - whatsapp_location - not: allOf: - required: - whatsapp_link - whatsapp_button - anyOf: - required: - whatsapp_image - required: - whatsapp_video - required: - whatsapp_audio - required: - whatsapp_document - required: - whatsapp_location - not: required: - whatsapp_location - whatsapp_message - not: required: - whatsapp_audio - whatsapp_message - if: required: - whatsapp_template then: allOf: - not: required: - whatsapp_audio - not: allOf: - anyOf: - required: - whatsapp_image - required: - whatsapp_video - required: - whatsapp_audio - required: - whatsapp_document - required: - whatsapp_location - not: allOf: - anyOf: - required: - whatsapp_image - required: - whatsapp_video - required: - whatsapp_audio - required: - whatsapp_document - required: - whatsapp_location - required: - whatsapp_header - if: required: - whatsapp_code then: required: - whatsapp_template