> For the complete documentation index, see [llms.txt](https://developer.ecall-messaging.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.ecall-messaging.com/api-references/rest-api/message.md).
# Message
Send a single text message (SMS, WhatsApp, or RCS) to one or more recipients, and query its delivery status. Status can be queried up to **seven days** after sending.
## Send a single message
> Sends a single message to one recipient (\`to\`) or a list of recipients (\`toList\`).\
> Supported channels: \*\*SMS\*\*, \*\*WhatsApp\*\*, \*\*RCS\*\*.\
> \
> \> \*\*Note:\*\* \`to\` and \`toList\` are mutually exclusive — passing both returns a\
> \> validation error.\
> \
> \### SMS character limits\
> \
> A single SMS page holds 160 characters (GSM) or 70 characters (UCS-2). Long messages\
> are split into pages (max. 10). Multi-part pages each lose 7 characters to sequencing\
> data, giving \*\*153 chars/page\*\* (GSM) or \*\*67 chars/page\*\* (UCS-2). The absolute\
> maximum is \*\*1530 characters\*\* (GSM) / \*\*670 characters\*\* (UCS-2).\
> \
> The maximum page count can also be configured per-message via \`content.options.pageLimit\`.\
> \
> \### WhatsApp\
> \
> Maximum message length is \*\*4096 characters\*\*. The sender must be the phone number of a\
> registered WhatsApp Business Account — contact eCall support to set it up. The \`Sticker\`\
> content type is not supported for WhatsApp.\
> \
> \### RCS\
> \
> Maximum message length is \*\*1000 characters\*\*. The RCS sender ID must be registered\
> with the RCS provider — contact eCall support to obtain it.
```json
{"openapi":"3.1.0","info":{"title":"eCall REST API","version":"2.0"},"tags":[{"name":"Message","description":"Send a single text message (SMS, WhatsApp, or RCS) to one or more recipients, and query its\ndelivery status. Status can be queried up to **seven days** after sending.\n"}],"servers":[{"url":"https://rest.ecall.ch","description":"eCall REST API (Production)"}],"security":[{"BasicAuth":[]}],"components":{"securitySchemes":{"BasicAuth":{"type":"http","scheme":"basic","description":"HTTP Basic Authentication. Encode `username:password` in Base64 and pass as:\n`Authorization: Basic `\n\nUse your eCall account credentials or a dedicated API sub-user created in the\neCall portal (**Interfaces → Overview**).\n"}},"schemas":{"MessageRequest":{"required":["channel","from","content"],"type":"object","description":"Request body for sending a single message. Use either `to` (single recipient)\nor `toList` (multiple recipients) — not both.\n","properties":{"channel":{"type":"string","description":"The messaging channel to use.\n\n| Value | Description |\n|-------|-------------|\n| `Sms` | SMS (also automatically routes to Pager or Voice for landline numbers if configured) |\n| `Whatsapp` | WhatsApp Business messaging |\n| `Rcs` | Rich Communication Services |\n","enum":["Sms","Whatsapp","Rcs"]},"from":{"type":"string","description":"Sender address.\n\n- **SMS:** Up to 16 numeric characters or up to 11 alphanumeric characters\n (ASCII 32–126). Test sender values carefully — not all providers accept all\n alphanumeric characters. Free accounts may only use the registered mobile number.\n- **WhatsApp:** Phone number of the registered WhatsApp Business Account in\n international format (e.g. `0041769999999`). Contact eCall support to set up.\n- **RCS:** Your RCS sender ID as assigned by the provider. Contact eCall support\n to register and obtain the sender ID.\n"},"to":{"type":["string","null"],"description":"Single recipient address in international format (e.g. `0041781234567` or\n`+41781234567`). Mutually exclusive with `toList`.\n"},"toList":{"type":["array","null"],"description":"List of recipients. Mutually exclusive with `to`. Returns a `messageIdList`\nin the response.\n","items":{"oneOf":[{"$ref":"#/components/schemas/ToAddressNumber"},{"$ref":"#/components/schemas/ToAddressPerson"},{"$ref":"#/components/schemas/ToAddressGroup"}]}},"sendDate":{"type":["string","null"],"description":"Scheduled send time in ISO 8601 format. If omitted, the message is sent immediately.\n"},"content":{"description":"Message content. For SMS, WhatsApp, and RCS, use `TextContent`.","oneOf":[{"$ref":"#/components/schemas/TextContent"},{"$ref":"#/components/schemas/ImageContent"},{"$ref":"#/components/schemas/DocumentContent"},{"$ref":"#/components/schemas/AudioContent"},{"$ref":"#/components/schemas/VideoContent"},{"$ref":"#/components/schemas/LocationContent"},{"$ref":"#/components/schemas/ContactContent"},{"$ref":"#/components/schemas/InteractiveContent"},{"$ref":"#/components/schemas/InteractiveReplyContent"},{"$ref":"#/components/schemas/TemplateContent"},{"$ref":"#/components/schemas/StickerContent"},{"$ref":"#/components/schemas/MediaContent"}]},"notification":{"$ref":"#/components/schemas/Notification"}},"additionalProperties":false},"ToAddressNumber":{"required":["address"],"type":"object","description":"A recipient identified by mobile number in international format.","allOf":[{"$ref":"#/components/schemas/ToAddress"}],"properties":{"address":{"type":"string","minLength":1,"description":"Mobile number in international format, e.g. `0041781234567` or `+41781234567`."}},"additionalProperties":false},"ToAddress":{"required":["type"],"type":"object","description":"Base type for a recipient address in a `toList`.","properties":{"type":{"$ref":"#/components/schemas/ToAddressType"}},"additionalProperties":false},"ToAddressType":{"type":"string","description":"Type of recipient address entry.","enum":["Number","Person","Group"]},"ToAddressPerson":{"required":["address"],"type":"object","description":"A recipient identified by name as stored in the eCall address book.\nFormat: `[Lastname] [Firstname]` (without brackets).\n","allOf":[{"$ref":"#/components/schemas/ToAddress"}],"properties":{"address":{"type":"string","minLength":1,"description":"Name from eCall address book. Format: Lastname Firstname."}},"additionalProperties":false},"ToAddressGroup":{"required":["address"],"type":"object","description":"A recipient group defined in the eCall address book.","allOf":[{"$ref":"#/components/schemas/ToAddress"}],"properties":{"address":{"type":"string","minLength":1,"description":"Group name as defined in the eCall address book."}},"additionalProperties":false},"TextContent":{"required":["text"],"type":"object","description":"Plain text content. The primary content type for SMS and RCS.\n\nFor SMS, the maximum length is determined by account settings (max. 10 pages / 1530 chars\nGSM). Text exceeding the limit is truncated. Use `options.pageLimit` to restrict to fewer\npages, or `options.smsType: Flash` to send a flash SMS.\n","allOf":[{"$ref":"#/components/schemas/MessageContent"}],"properties":{"text":{"type":"string","minLength":1,"description":"The message text. UTF-8 encoded."}},"additionalProperties":false},"MessageContent":{"required":["type"],"type":"object","description":"Base type for all message content objects. Use `type` to identify the subtype.","properties":{"type":{"$ref":"#/components/schemas/ContentType"},"options":{"description":"Channel-specific content options (currently only `SmsContentOptions`).","oneOf":[{"$ref":"#/components/schemas/SmsContentOptions"},{"type":"null"}]}},"additionalProperties":false},"ContentType":{"type":"string","description":"Discriminator for message content type.","enum":["Text","Template","Image","Video","Document","Location","Audio","Sticker","Contacts","Interactive","InteractiveReply"]},"SmsContentOptions":{"type":"object","description":"SMS-specific options that override account-level settings for this message.","allOf":[{"$ref":"#/components/schemas/Options"}],"properties":{"forceGsm":{"type":["boolean","null"],"description":"If `true`, characters outside the GSM-7 character set are not allowed\n(they would otherwise cause UCS-2 encoding, reducing capacity per page).\n"},"pageLimit":{"type":["integer","null"],"format":"int32","description":"Maximum number of SMS pages. Maximum value is 10."},"smsType":{"$ref":"#/components/schemas/MessageType"}},"additionalProperties":false},"Options":{"required":["type"],"type":"object","properties":{"type":{"$ref":"#/components/schemas/OptionType"}},"additionalProperties":false},"OptionType":{"type":"string","enum":["SmsContentOptions"]},"MessageType":{"type":"string","description":"SMS delivery type:\n- `Standard` – Normal SMS (default).\n- `Flash` – Flash SMS, displayed directly on the recipient's screen without being stored.\n- `PrioPlus` – Priority delivery (if supported by account).\n","enum":["Standard","Flash","PrioPlus"]},"ImageContent":{"type":"object","description":"Image message content.","allOf":[{"$ref":"#/components/schemas/MediaContent"}],"properties":{"caption":{"type":["string","null"],"description":"Optional image caption."}},"additionalProperties":false},"MediaContent":{"type":"object","description":"Base type for media content (images, audio, video, documents, stickers).","allOf":[{"$ref":"#/components/schemas/MessageContent"}],"properties":{"mediaId":{"type":["string","null"],"description":"ID of a previously uploaded media file (from `POST /api/v2/media`)."},"url":{"type":["string","null"],"description":"Public HTTP/HTTPS URL of the media file. Use `mediaId` or `url`, not both."}},"additionalProperties":false},"DocumentContent":{"type":"object","description":"Document/file message content.","allOf":[{"$ref":"#/components/schemas/MediaContent"}],"properties":{"caption":{"type":["string","null"],"description":"Currently not supported."},"filename":{"type":["string","null"],"description":"Display filename for the document."}},"additionalProperties":false},"AudioContent":{"type":"object","description":"Audio message content.","allOf":[{"$ref":"#/components/schemas/MediaContent"}],"additionalProperties":false},"VideoContent":{"type":"object","description":"Video message content.","allOf":[{"$ref":"#/components/schemas/MediaContent"}],"properties":{"caption":{"type":["string","null"],"description":"Optional video caption."}},"additionalProperties":false},"LocationContent":{"type":"object","description":"Geographic location message content.","allOf":[{"$ref":"#/components/schemas/MessageContent"}],"properties":{"longitude":{"type":"number","format":"double","description":"Longitude coordinate."},"latitude":{"type":"number","format":"double","description":"Latitude coordinate."},"name":{"type":["string","null"],"description":"Optional location name."},"address":{"type":["string","null"],"description":"Optional address text."}},"additionalProperties":false},"ContactContent":{"type":"object","description":"vCard contact message content.","allOf":[{"$ref":"#/components/schemas/MessageContent"}],"properties":{"contacts":{"type":["array","null"],"items":{"$ref":"#/components/schemas/ContactData"}}},"additionalProperties":false},"ContactData":{"required":["name"],"type":"object","properties":{"name":{"$ref":"#/components/schemas/NameData"},"birthDay":{"type":["string","null"],"description":"Birthday in `YYYY-MM-DD` format."},"organization":{"$ref":"#/components/schemas/OrganizationData"},"addresses":{"type":["array","null"],"items":{"$ref":"#/components/schemas/AddressData"}},"phones":{"type":["array","null"],"items":{"$ref":"#/components/schemas/PhoneData"}},"urls":{"type":["array","null"],"items":{"$ref":"#/components/schemas/UrlData"}}},"additionalProperties":false},"NameData":{"required":["formattedName"],"type":"object","properties":{"formattedName":{"type":"string","minLength":1},"firstName":{"type":["string","null"]},"lastName":{"type":["string","null"]},"middleName":{"type":["string","null"]},"suffix":{"type":["string","null"]},"prefix":{"type":["string","null"]}},"additionalProperties":false},"OrganizationData":{"type":"object","properties":{"company":{"type":["string","null"]},"department":{"type":["string","null"]},"title":{"type":["string","null"]}},"additionalProperties":false},"AddressData":{"type":"object","properties":{"street":{"type":["string","null"]},"city":{"type":["string","null"]},"state":{"type":["string","null"]},"zip":{"type":["string","null"]},"country":{"type":["string","null"]},"countryCode":{"type":["string","null"]},"type":{"type":["string","null"]}},"additionalProperties":false},"PhoneData":{"type":"object","properties":{"phone":{"type":["string","null"]},"type":{"type":["string","null"]}},"additionalProperties":false},"UrlData":{"type":"object","properties":{"url":{"type":["string","null"]},"type":{"type":["string","null"]}},"additionalProperties":false},"InteractiveContent":{"required":["action"],"type":"object","description":"Interactive message with buttons or a list (e.g. for WhatsApp/RCS).","allOf":[{"$ref":"#/components/schemas/MessageContent"}],"properties":{"header":{"oneOf":[{"$ref":"#/components/schemas/InteractiveTextHeader"},{"$ref":"#/components/schemas/InteractiveImageHeader"},{"$ref":"#/components/schemas/InteractiveVideoHeader"},{"$ref":"#/components/schemas/InteractiveDocumentHeader"},{"type":"null"}]},"body":{"$ref":"#/components/schemas/InteractiveBody"},"footer":{"$ref":"#/components/schemas/InteractiveFooter"},"action":{"oneOf":[{"$ref":"#/components/schemas/InteractiveButtonAction"},{"$ref":"#/components/schemas/InteractiveListAction"}]}},"additionalProperties":false},"InteractiveTextHeader":{"required":["text"],"type":"object","allOf":[{"$ref":"#/components/schemas/InteractiveHeader"}],"properties":{"text":{"type":"string","minLength":1,"maxLength":60,"description":"Header text. Supports emojis but not markdown."}},"additionalProperties":false},"InteractiveHeader":{"required":["type"],"type":"object","properties":{"type":{"$ref":"#/components/schemas/InteractiveHeaderType"}},"additionalProperties":false},"InteractiveHeaderType":{"type":"string","enum":["Text","Video","Image","Document"]},"InteractiveImageHeader":{"type":"object","allOf":[{"$ref":"#/components/schemas/InteractiveMediaHeader"}],"additionalProperties":false},"InteractiveMediaHeader":{"type":"object","allOf":[{"$ref":"#/components/schemas/InteractiveHeader"}],"properties":{"mediaId":{"type":["string","null"],"description":"ID of an uploaded media file. Required if `url` is not set."},"url":{"type":["string","null"],"description":"Public HTTP/HTTPS URL of the media. Required if `mediaId` is not set."}},"additionalProperties":false},"InteractiveVideoHeader":{"type":"object","allOf":[{"$ref":"#/components/schemas/InteractiveMediaHeader"}],"additionalProperties":false},"InteractiveDocumentHeader":{"type":"object","allOf":[{"$ref":"#/components/schemas/InteractiveMediaHeader"}],"additionalProperties":false},"InteractiveBody":{"required":["text"],"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":1024,"description":"Body text. Supports emojis, markdown, and links."}},"additionalProperties":false},"InteractiveFooter":{"required":["text"],"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":60,"description":"Footer text. Supports emojis, markdown, and links."}},"additionalProperties":false},"InteractiveButtonAction":{"required":["buttons"],"type":"object","allOf":[{"$ref":"#/components/schemas/InteractiveAction"}],"properties":{"buttons":{"type":"array","minItems":1,"maxItems":3,"items":{"oneOf":[{"$ref":"#/components/schemas/InteractiveButtonActionReplyButton"}]}}},"additionalProperties":false},"InteractiveAction":{"required":["type"],"type":"object","properties":{"type":{"$ref":"#/components/schemas/InteractiveActionType"}},"additionalProperties":false},"InteractiveActionType":{"type":"string","enum":["Button","List"]},"InteractiveButtonActionReplyButton":{"required":["id","title"],"type":"object","allOf":[{"$ref":"#/components/schemas/InteractiveButtonActionButton"}],"properties":{"id":{"type":"string","minLength":1,"maxLength":256,"description":"Unique button ID returned in the webhook when clicked."},"title":{"type":"string","minLength":1,"maxLength":20,"description":"Button label text. No emojis or markdown."}},"additionalProperties":false},"InteractiveButtonActionButton":{"required":["type"],"type":"object","properties":{"type":{"$ref":"#/components/schemas/InteractiveButtonActionButtonType"}},"additionalProperties":false},"InteractiveButtonActionButtonType":{"type":"string","enum":["Reply"]},"InteractiveListAction":{"required":["button","sections"],"type":"object","allOf":[{"$ref":"#/components/schemas/InteractiveAction"}],"properties":{"button":{"type":"string","minLength":1,"maxLength":20,"description":"Button label. No emojis or markdown."},"sections":{"type":"array","minItems":1,"maxItems":10,"description":"Max. 10 rows across all sections.","items":{"$ref":"#/components/schemas/InteractiveListActionSection"}}},"additionalProperties":false},"InteractiveListActionSection":{"required":["rows"],"type":"object","properties":{"title":{"type":["string","null"],"minLength":1,"maxLength":24,"description":"Required if the message has more than one section."},"rows":{"type":"array","minItems":1,"maxItems":10,"items":{"$ref":"#/components/schemas/InteractiveListActionRow"}}},"additionalProperties":false},"InteractiveListActionRow":{"required":["id","title"],"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":200},"title":{"type":"string","minLength":1,"maxLength":24},"description":{"type":["string","null"],"minLength":1,"maxLength":72}},"additionalProperties":false},"InteractiveReplyContent":{"type":"object","description":"Content received when a user interacts with an interactive message.","allOf":[{"$ref":"#/components/schemas/MessageContent"}],"properties":{"reply":{"oneOf":[{"$ref":"#/components/schemas/InteractiveButtonReply"},{"$ref":"#/components/schemas/InteractiveListReply"},{"type":"null"}]}},"additionalProperties":false},"InteractiveButtonReply":{"type":"object","allOf":[{"$ref":"#/components/schemas/InteractiveReplyContentReply"}],"properties":{"id":{"type":["string","null"]},"title":{"type":["string","null"]}},"additionalProperties":false},"InteractiveReplyContentReply":{"required":["type"],"type":"object","properties":{"type":{"$ref":"#/components/schemas/InteractiveReplyType"}},"additionalProperties":false},"InteractiveReplyType":{"type":"string","enum":["Button","List"]},"InteractiveListReply":{"type":"object","allOf":[{"$ref":"#/components/schemas/InteractiveReplyContentReply"}],"properties":{"id":{"type":["string","null"]},"title":{"type":["string","null"]},"description":{"type":["string","null"]}},"additionalProperties":false},"TemplateContent":{"required":["namespace","name","language"],"type":"object","description":"Pre-approved message template (e.g. for WhatsApp Business).","allOf":[{"$ref":"#/components/schemas/MessageContent"}],"properties":{"namespace":{"type":"string","minLength":1},"name":{"type":"string","minLength":1},"language":{"$ref":"#/components/schemas/TemplateLanguage"},"components":{"type":["array","null"],"items":{"oneOf":[{"$ref":"#/components/schemas/TemplateBodyComponent"},{"$ref":"#/components/schemas/TemplateButtonComponent"},{"$ref":"#/components/schemas/TemplateHeaderComponent"},{"$ref":"#/components/schemas/TemplateQuickReplyButtonComponent"},{"$ref":"#/components/schemas/TemplateUrlButtonComponent"}]}}},"additionalProperties":false},"TemplateLanguage":{"required":["code"],"type":"object","properties":{"policy":{"$ref":"#/components/schemas/TemplateLanguagePolicy"},"code":{"$ref":"#/components/schemas/TemplateLanguageCode"}},"additionalProperties":false},"TemplateLanguagePolicy":{"type":"string","enum":["Deterministic"]},"TemplateLanguageCode":{"type":"string","description":"BCP 47 language code for the template.","enum":["af","sq","ar","az","bn","bg","ca","zh_CN","zh_HK","zh_TW","hr","cs","da","nl","en","en_GB","en_US","et","fil","fi","fr","ka","de","el","gu","ha","he","hi","hu","id","ga","it","ja","kn","kk","rw_RW","ko","ky_KG","lo","lv","lt","mk","ms","ml","mr","nb","fa","pl","pt_BR","pt_PT","pa","ro","ru","sr","sk","sl","es","es_AR","es_ES","es_MX","sw","sv","ta","te","th","tr","uk","ur","uz","vi","zu"]},"TemplateBodyComponent":{"type":"object","allOf":[{"$ref":"#/components/schemas/TemplateComponent"}],"additionalProperties":false},"TemplateComponent":{"required":["type","parameters"],"type":"object","properties":{"type":{"$ref":"#/components/schemas/TemplateComponentType"},"parameters":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/TemplateTextParameter"},{"$ref":"#/components/schemas/TemplateImageParameter"},{"$ref":"#/components/schemas/TemplateVideoParameter"},{"$ref":"#/components/schemas/TemplateDocumentParameter"},{"$ref":"#/components/schemas/TemplateDateTimeParameter"},{"$ref":"#/components/schemas/TemplateCurrencyParameter"},{"$ref":"#/components/schemas/TemplatePayloadParameter"},{"$ref":"#/components/schemas/TemplateMediaParameter"}]}}},"additionalProperties":false},"TemplateComponentType":{"type":"string","enum":["Header","Body","QuickReplyButton","UrlButton"]},"TemplateTextParameter":{"required":["text"],"type":"object","allOf":[{"$ref":"#/components/schemas/TemplateParameter"}],"properties":{"text":{"type":"string","minLength":1}},"additionalProperties":false},"TemplateParameter":{"required":["type"],"type":"object","properties":{"type":{"$ref":"#/components/schemas/TemplateParameterType"}},"additionalProperties":false},"TemplateParameterType":{"type":"string","enum":["Text","Image","Video","Document","DateTime","Currency","Payload"]},"TemplateImageParameter":{"type":"object","allOf":[{"$ref":"#/components/schemas/TemplateMediaParameter"}],"additionalProperties":false},"TemplateMediaParameter":{"type":"object","allOf":[{"$ref":"#/components/schemas/TemplateParameter"}],"properties":{"mediaId":{"type":["string","null"],"description":"ID of an uploaded media file. Required if `url` is not set."},"url":{"type":["string","null"],"description":"Public HTTP/HTTPS URL. Required if `mediaId` is not set."}},"additionalProperties":false},"TemplateVideoParameter":{"type":"object","allOf":[{"$ref":"#/components/schemas/TemplateMediaParameter"}],"additionalProperties":false},"TemplateDocumentParameter":{"type":"object","allOf":[{"$ref":"#/components/schemas/TemplateMediaParameter"}],"properties":{"filename":{"type":["string","null"]}},"additionalProperties":false},"TemplateDateTimeParameter":{"required":["dateTime"],"type":"object","allOf":[{"$ref":"#/components/schemas/TemplateParameter"}],"properties":{"dateTime":{"type":"string","format":"date-time","description":"RFC 3339 date-time string."}},"additionalProperties":false},"TemplateCurrencyParameter":{"required":["code","amount","fallbackValue"],"type":"object","allOf":[{"$ref":"#/components/schemas/TemplateParameter"}],"properties":{"code":{"type":"string","minLength":3,"maxLength":3,"description":"ISO 4217 currency code."},"amount":{"type":"integer","format":"int32","description":"Amount in cents × 1000. E.g. CHF 100.99 → 100990."},"fallbackValue":{"type":"string","minLength":1,"description":"Displayed if localization fails."}},"additionalProperties":false},"TemplatePayloadParameter":{"required":["payload"],"type":"object","allOf":[{"$ref":"#/components/schemas/TemplateParameter"}],"properties":{"payload":{"type":"string","minLength":1}},"additionalProperties":false},"TemplateButtonComponent":{"required":["index"],"type":"object","allOf":[{"$ref":"#/components/schemas/TemplateComponent"}],"properties":{"index":{"type":"integer","format":"int32"}},"additionalProperties":false},"TemplateHeaderComponent":{"type":"object","allOf":[{"$ref":"#/components/schemas/TemplateComponent"}],"additionalProperties":false},"TemplateQuickReplyButtonComponent":{"type":"object","allOf":[{"$ref":"#/components/schemas/TemplateButtonComponent"}],"additionalProperties":false},"TemplateUrlButtonComponent":{"type":"object","allOf":[{"$ref":"#/components/schemas/TemplateButtonComponent"}],"additionalProperties":false},"StickerContent":{"type":"object","description":"Sticker message content.","allOf":[{"$ref":"#/components/schemas/MediaContent"}],"additionalProperties":false},"Notification":{"required":["addresses"],"type":"object","description":"Configures push notifications for delivery status updates. eCall will call the\nspecified addresses when the `forEvent` condition is met.\n","properties":{"forEvent":{"type":["string","null"],"description":"Specifies which events trigger a notification.\n\n| Value | Description |\n|-------|-------------|\n| `SuccessOnly` | **(Default)** Only when delivery is confirmed by the device. |\n| `FinalOnly` | When delivery is confirmed **or** failed (any final status). |\n| `All` | Same as `FinalOnly`, plus when the job is delayed by the provider. |\n| `ErrorOnly` | Only when sending failed. |\n","enum":["SuccessOnly","FinalOnly","All","ErrorOnly"],"default":"SuccessOnly"},"addresses":{"type":"array","minItems":1,"description":"List of notification addresses. Max. total combined length: **200 characters**.\nValidation fails at the first invalid address.\n","items":{"oneOf":[{"$ref":"#/components/schemas/EmailNotificationAddress"},{"$ref":"#/components/schemas/SmsNotificationAddress"},{"$ref":"#/components/schemas/UrlNotificationAddress"}]}}},"additionalProperties":false},"EmailNotificationAddress":{"required":["address"],"type":"object","description":"Notification delivered by email.","allOf":[{"$ref":"#/components/schemas/NotificationAddress"}],"properties":{"address":{"type":"string","minLength":1,"description":"Email address."}},"additionalProperties":false},"NotificationAddress":{"required":["type"],"type":"object","properties":{"type":{"$ref":"#/components/schemas/NotificationAddressType"}},"additionalProperties":false},"NotificationAddressType":{"type":"string","description":"Type of notification address:\n- `Email` – eCall sends an email to the address.\n- `Sms` – eCall sends an SMS to the number.\n- `Url` – eCall makes an HTTP GET request to the URL with status data in the query string.\n- `UrlPost` – eCall makes an HTTP POST request to the URL with status data as JSON.\n","enum":["Sms","Email","Url","UrlPost"]},"SmsNotificationAddress":{"required":["address"],"type":"object","description":"Notification delivered by SMS.","allOf":[{"$ref":"#/components/schemas/NotificationAddress"}],"properties":{"address":{"type":"string","minLength":1,"description":"Mobile number in international format."}},"additionalProperties":false},"UrlNotificationAddress":{"required":["address"],"type":"object","description":"Notification delivered via HTTP. Use type `Url` for GET requests or `UrlPost`\nfor POST requests (JSON body).\n","allOf":[{"$ref":"#/components/schemas/NotificationAddress"}],"properties":{"address":{"type":"string","minLength":1,"description":"The URL eCall will call."}},"additionalProperties":false},"MessageResult":{"type":"object","description":"Response from a successful single message send request.\n\n- When `to` was used: only `messageId` is set.\n- When `toList` was used: `messageIdList` is set; `messageId` is empty.\n","properties":{"messageId":{"type":["string","null"],"description":"Unique identifier of the sent message. Use this for status queries."},"messageIdList":{"type":["array","null"],"description":"List of message IDs per recipient (only set when `toList` was used).","items":{"$ref":"#/components/schemas/MessageIdAddressPair"}},"timestamp":{"type":"string","format":"date-time","description":"UTC timestamp when the response was returned."}},"additionalProperties":false},"MessageIdAddressPair":{"type":"object","description":"Mapping of a message ID to its recipient address.","properties":{"messageId":{"type":["string","null"]},"address":{"type":["string","null"]}},"additionalProperties":false},"Error":{"type":"object","description":"Error response returned for `4xx` and `5xx` HTTP status codes.","properties":{"errorCode":{"$ref":"#/components/schemas/ErrorCode"},"errorMessage":{"type":["string","null"],"description":"High-level human-readable description of the error."},"errorDetails":{"description":"Detailed breakdown of validation errors, if applicable.","oneOf":[{"$ref":"#/components/schemas/ParameterErrorDetails"},{"type":"null"}]}},"additionalProperties":false},"ErrorCode":{"type":"string","description":"Machine-readable error code indicating why the request failed.\n\n| Code | Description |\n|------|-------------|\n| `InvalidContent` | JSON validation failed — bad parameter value. Check `errorDetails`. |\n| `InsufficientPoints` | Account has insufficient points/credits to send this message. |\n| `TooManyMessagesSameReceiver` | Too many messages sent to the same recipient (anti-spam). |\n| `TooManyMessagesSameReceiverAndContent` | Too many identical messages to the same recipient. |\n| `RequestMissing` | Request body is missing or empty. |\n| `UnknownContentType` | The specified `content.type` is not recognised. |\n| `InvalidSenderAccount` | The sender address is not valid for this account. |\n| `CannotConvertMediaBody` | Media file could not be processed. |\n| `PointSubstractionError` | Error deducting points from account balance. |\n| `AdrCountryNotWhitelisted` | Recipient country is not whitelisted for this account. |\n| `AdrCountryWhitelistLimitExceeded` | Country whitelist limit exceeded. |\n","enum":["Error1","Error2","RequestMissing","CannotConvertMediaBody","UnknownContentType","InvalidSenderAccount","InvalidContent","InsufficientPoints","PointSubstractionError","TooManyMessagesSameReceiver","TooManyMessagesSameReceiverAndContent","AdrCountryNotWhitelisted","AdrCountryWhitelistLimitExceeded","AdrCountryWhitelistLimitReachedButNotBlockedCountries"]},"ParameterErrorDetails":{"type":"object","description":"Detailed error information for parameter validation failures.","allOf":[{"$ref":"#/components/schemas/ErrorDetails"}],"properties":{"errors":{"type":["array","null"],"description":"List of individual field validation errors.","items":{"$ref":"#/components/schemas/ParameterErrorDetailsEntry"}}},"additionalProperties":false},"ErrorDetails":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ErrorDetailsType"}},"additionalProperties":false},"ErrorDetailsType":{"type":"string","enum":["Parameter"]},"ParameterErrorDetailsEntry":{"type":"object","description":"A single field-level validation error.","properties":{"parameter":{"type":["string","null"],"description":"Name of the field that caused the error."},"messages":{"type":["array","null"],"description":"Human-readable error messages for this field.","items":{"type":"string"}}},"additionalProperties":false}},"responses":{"BadRequest":{"description":"The request is invalid. This may be caused by a missing required parameter,\nan invalid value, or a constraint violation. Check the `errorCode` and\n`errorDetails` in the response body for specifics.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"The `Authorization` header is missing or the credentials are invalid.\nVerify your username, password, and Base64 encoding.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalServerError":{"description":"An unexpected error occurred on the eCall server. Retry after a short delay.\nIf the problem persists, contact eCall support and include the `x-f24-request-id`\nheader value from the response.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/v2/message":{"post":{"tags":["Message"],"summary":"Send a single message","operationId":"sendMessage","description":"Sends a single message to one recipient (`to`) or a list of recipients (`toList`).\nSupported channels: **SMS**, **WhatsApp**, **RCS**.\n\n> **Note:** `to` and `toList` are mutually exclusive — passing both returns a\n> validation error.\n\n### SMS character limits\n\nA single SMS page holds 160 characters (GSM) or 70 characters (UCS-2). Long messages\nare split into pages (max. 10). Multi-part pages each lose 7 characters to sequencing\ndata, giving **153 chars/page** (GSM) or **67 chars/page** (UCS-2). The absolute\nmaximum is **1530 characters** (GSM) / **670 characters** (UCS-2).\n\nThe maximum page count can also be configured per-message via `content.options.pageLimit`.\n\n### WhatsApp\n\nMaximum message length is **4096 characters**. The sender must be the phone number of a\nregistered WhatsApp Business Account — contact eCall support to set it up. The `Sticker`\ncontent type is not supported for WhatsApp.\n\n### RCS\n\nMaximum message length is **1000 characters**. The RCS sender ID must be registered\nwith the RCS provider — contact eCall support to obtain it.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageRequest"}}}},"responses":{"200":{"description":"Message accepted successfully.","headers":{},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageResult"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```
## Get message status
> Retrieves the current delivery status of a previously sent message.\
> The \`messageId\` is obtained from the send response.\
> \
> \> Status can be queried up to \*\*seven days\*\* after sending.\
> \
> \### Voice channel note\
> \
> Voice messages cannot be sent directly via the REST API. However, if the\
> \*\*"Convert SMS to voice for landline numbers"\*\* option is enabled in the eCall portal\
> (Account Settings → SMS), SMS sent to Swiss or German landline numbers are automatically\
> converted to voice calls. A status query on such a message returns \`channel: Voice\` with\
> voice-specific status codes.
```json
{"openapi":"3.1.0","info":{"title":"eCall REST API","version":"2.0"},"tags":[{"name":"Message","description":"Send a single text message (SMS, WhatsApp, or RCS) to one or more recipients, and query its\ndelivery status. Status can be queried up to **seven days** after sending.\n"}],"servers":[{"url":"https://rest.ecall.ch","description":"eCall REST API (Production)"}],"security":[{"BasicAuth":[]}],"components":{"securitySchemes":{"BasicAuth":{"type":"http","scheme":"basic","description":"HTTP Basic Authentication. Encode `username:password` in Base64 and pass as:\n`Authorization: Basic `\n\nUse your eCall account credentials or a dedicated API sub-user created in the\neCall portal (**Interfaces → Overview**).\n"}},"schemas":{"MessageStatusData":{"type":"object","description":"Delivery status of a single message.","properties":{"channel":{"type":["string","null"],"description":"Channel over which the message was sent (`Sms`, `Whatsapp`, `Rcs`, `Voice`, `Pager`)."},"messageId":{"type":["string","null"],"description":"Unique identifier of the message."},"status":{"$ref":"#/components/schemas/MessageStatus"},"reasonCode":{"type":"integer","format":"int32","description":"Provider-level result code. `0` indicates success. See the table below for error codes.\n\n| Code | Description |\n|------|-------------|\n| `3020` | Timeout connecting to provider (pager) |\n| `5111` | Text too long (pager) |\n| `5112` | Invalid receiver number (pager) |\n| `5120` | Not a pager number |\n| `5121` | Invalid characters in receiver number (pager) |\n| `5155` | Too much traffic (pager) |\n| `5502` | Syntax error |\n| `5504` | Maximum messages for this address exceeded |\n| `5506` | Analog-to-digital converter invalid |\n| `5509` | Invalid receiver number |\n| `5510` | Too many messages for same receiver |\n| `5511` | Too many messages with same content for same receiver |\n| `5513` | Blacklisted (callback, address, or content) |\n| `5514` | Blocked by outbound filter rule |\n"},"reason":{"type":["string","null"],"description":"Human-readable provider result text."},"timestamp":{"type":"string","format":"date-time","description":"UTC timestamp of the latest status update."},"from":{"type":["string","null"],"description":"Sender address."},"to":{"type":["string","null"],"description":"Recipient address in international format."},"pageTotal":{"type":["integer","null"],"format":"int32","description":"SMS only: Total number of pages the message was split into."}},"additionalProperties":false},"MessageStatus":{"type":"string","description":"Delivery status of a message. Whether a status is **final** (no further updates expected)\ndepends on the channel:\n\n### SMS\n| Status | Final | Description |\n|--------|:-----:|-------------|\n| `Pending` | ☐ | Being transmitted to provider. |\n| `Sent` | ☐/☒ | Sent by provider. May become final after 4 days without a delivery report. |\n| `Delivered` | ☒ | Confirmed received by recipient device. |\n| `DeliveryFailed` | ☒ | Could not be delivered. |\n| `Failed` | ☒ | Sending failed. See `reason` for details. |\n\n### Pager\n| Status | Final | Description |\n|--------|:-----:|-------------|\n| `Pending` | ☐ | Being transmitted. |\n| `Sent` | ☒ | Sent successfully. |\n| `Failed` | ☒ | Sending failed. |\n\n### Voice (auto-converted SMS to landline)\n| Status | Final | Description |\n|--------|:-----:|-------------|\n| `Pending` | ☐ | Being transmitted. |\n| `Sent` | ☐ | Handed off to voice system. |\n| `Played` | ☐/☒ | Played on device. Final only if recipient hung up without acknowledging. |\n| `Played_with_receipt` | ☒ | Played and recipient confirmed. |\n| `Next_try_pending` | ☐ | No connection yet; retrying in 15 min. |\n| `Failed` | ☒ | Sending failed. |\n\n### WhatsApp\n| Status | Final | Description |\n|--------|:-----:|-------------|\n| `Pending` | ☐ | Being transmitted to provider. |\n| `Sent` | ☐ | Sent by provider. |\n| `Delivered` | ☐ | Received by device. |\n| `Read` | ☒ | Read by recipient. |\n| `Failed` | ☒ | Sending failed. |\n\n### RCS\n| Status | Final | Description |\n|--------|:-----:|-------------|\n| `Pending` | ☐ | Being transmitted. |\n| `Sent` | ☐ | Sent by provider. |\n| `Delivered` | ☐ | Received by device. |\n| `Displayed` | ☒ | Displayed on device. |\n| `Rejected` | ☒ | Rejected by provider. |\n| `Expired` | ☒ | Validity period exceeded. |\n","enum":["Pending","Sent","Delivered","Read","Failed","Deleted","Transmitted","DeliveryFailed","Played","Played_with_feedback","Played_with_receipt","Next_try_pending","Displayed","Rejected","Expired"]},"Error":{"type":"object","description":"Error response returned for `4xx` and `5xx` HTTP status codes.","properties":{"errorCode":{"$ref":"#/components/schemas/ErrorCode"},"errorMessage":{"type":["string","null"],"description":"High-level human-readable description of the error."},"errorDetails":{"description":"Detailed breakdown of validation errors, if applicable.","oneOf":[{"$ref":"#/components/schemas/ParameterErrorDetails"},{"type":"null"}]}},"additionalProperties":false},"ErrorCode":{"type":"string","description":"Machine-readable error code indicating why the request failed.\n\n| Code | Description |\n|------|-------------|\n| `InvalidContent` | JSON validation failed — bad parameter value. Check `errorDetails`. |\n| `InsufficientPoints` | Account has insufficient points/credits to send this message. |\n| `TooManyMessagesSameReceiver` | Too many messages sent to the same recipient (anti-spam). |\n| `TooManyMessagesSameReceiverAndContent` | Too many identical messages to the same recipient. |\n| `RequestMissing` | Request body is missing or empty. |\n| `UnknownContentType` | The specified `content.type` is not recognised. |\n| `InvalidSenderAccount` | The sender address is not valid for this account. |\n| `CannotConvertMediaBody` | Media file could not be processed. |\n| `PointSubstractionError` | Error deducting points from account balance. |\n| `AdrCountryNotWhitelisted` | Recipient country is not whitelisted for this account. |\n| `AdrCountryWhitelistLimitExceeded` | Country whitelist limit exceeded. |\n","enum":["Error1","Error2","RequestMissing","CannotConvertMediaBody","UnknownContentType","InvalidSenderAccount","InvalidContent","InsufficientPoints","PointSubstractionError","TooManyMessagesSameReceiver","TooManyMessagesSameReceiverAndContent","AdrCountryNotWhitelisted","AdrCountryWhitelistLimitExceeded","AdrCountryWhitelistLimitReachedButNotBlockedCountries"]},"ParameterErrorDetails":{"type":"object","description":"Detailed error information for parameter validation failures.","allOf":[{"$ref":"#/components/schemas/ErrorDetails"}],"properties":{"errors":{"type":["array","null"],"description":"List of individual field validation errors.","items":{"$ref":"#/components/schemas/ParameterErrorDetailsEntry"}}},"additionalProperties":false},"ErrorDetails":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ErrorDetailsType"}},"additionalProperties":false},"ErrorDetailsType":{"type":"string","enum":["Parameter"]},"ParameterErrorDetailsEntry":{"type":"object","description":"A single field-level validation error.","properties":{"parameter":{"type":["string","null"],"description":"Name of the field that caused the error."},"messages":{"type":["array","null"],"description":"Human-readable error messages for this field.","items":{"type":"string"}}},"additionalProperties":false}},"responses":{"BadRequest":{"description":"The request is invalid. This may be caused by a missing required parameter,\nan invalid value, or a constraint violation. Check the `errorCode` and\n`errorDetails` in the response body for specifics.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"The `Authorization` header is missing or the credentials are invalid.\nVerify your username, password, and Base64 encoding.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"The requested resource (message ID, media ID, etc.) was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalServerError":{"description":"An unexpected error occurred on the eCall server. Retry after a short delay.\nIf the problem persists, contact eCall support and include the `x-f24-request-id`\nheader value from the response.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/v2/message/{messageId}":{"get":{"tags":["Message"],"summary":"Get message status","operationId":"getMessageStatus","description":"Retrieves the current delivery status of a previously sent message.\nThe `messageId` is obtained from the send response.\n\n> Status can be queried up to **seven days** after sending.\n\n### Voice channel note\n\nVoice messages cannot be sent directly via the REST API. However, if the\n**\"Convert SMS to voice for landline numbers\"** option is enabled in the eCall portal\n(Account Settings → SMS), SMS sent to Swiss or German landline numbers are automatically\nconverted to voice calls. A status query on such a message returns `channel: Voice` with\nvoice-specific status codes.\n","parameters":[{"name":"messageId","in":"path","required":true,"description":"Unique message identifier as returned in the send response.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Status retrieved successfully.","headers":{},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageStatusData"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://developer.ecall-messaging.com/api-references/rest-api/message.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.