openapi: 3.1.0 info: title: SMSMobileAPI version: 2026-11-08 summary: Turn real mobile phones into programmable communication endpoints. description: | SMSMobileAPI connects a mobile phone, its SIM and existing number to software. Use this API to work with SMS, calls, WhatsApp, Telegram, notifications, e-mail and connected devices. Refer to the public documentation for account-specific capabilities and the latest operational guidance. contact: name: SMSMobileAPI Support url: https://smsmobileapi.com/ license: name: MIT identifier: MIT servers: - url: https://api.smsmobileapi.com description: Production externalDocs: description: SMSMobileAPI developer documentation url: https://smsmobileapi.com/documentations-api-smsmobileapi/ security: - ApiKeyQuery: [] tags: - name: SMS description: Send, receive and inspect SMS activity. - name: Devices description: Connected mobile gateways. - name: Calls description: Missed, incoming and outgoing call activity. - name: WhatsApp description: Send and consent-based retrieval workflows. - name: Notifications description: Internal notifications delivered to connected mobiles. - name: Email description: Send and retrieve e-mail through configured mailboxes. - name: Telegram description: Send text or files and read new private messages through the customer's connected Telegram account. paths: /sendsms/: post: tags: [SMS, WhatsApp] operationId: sendMessage summary: Send an SMS or WhatsApp message description: | Queues a message. Omit `waonly` for SMS. Set `waonly=yes` for WhatsApp-only delivery in a connected WhatsApp environment. A successful response means that the platform accepted the job; delivery remains asynchronous. requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object required: [apikey, recipients, message] properties: apikey: type: string recipients: type: string examples: ["+15551234567"] message: type: string sIdentifiant: type: string description: Specific connected mobile SID. port: type: integer enum: [1, 2] shorturl: type: integer enum: [0, 1] schedule_timestamp: type: integer description: UTC Unix timestamp from which the message may be sent. waonly: type: string enum: ["yes"] description: Set to yes for WhatsApp-only delivery. url_media: type: string format: uri description: Public HTTPS media URL for supported WhatsApp media. responses: "200": description: Message accepted or a documented application error returned. content: application/json: schema: $ref: "#/components/schemas/SendMessageResponse" "400": { $ref: "#/components/responses/BadRequest" } "403": { $ref: "#/components/responses/Forbidden" } "429": { $ref: "#/components/responses/TooManyRequests" } /getsms/: get: tags: [SMS] operationId: listReceivedSms summary: List received SMS parameters: - $ref: "#/components/parameters/AfterTimestamp" - name: sIdentifiantPhone in: query schema: { type: string } description: Filter by receiving mobile SID. - name: onlyunread in: query schema: { type: string, enum: ["yes"] } responses: "200": description: Received SMS list. content: application/json: schema: $ref: "#/components/schemas/ReceivedSmsResponse" "403": { $ref: "#/components/responses/Forbidden" } /log/sent/sms/: get: tags: [SMS] operationId: listSentSms summary: List SMS submitted through the API parameters: - name: guid_message in: query schema: { type: string } - name: keyword in: query schema: { type: string } - name: error_api in: query schema: { type: integer, enum: [0, 1] } - name: error_mobile in: query schema: { type: integer, enum: [0, 1] } responses: "200": description: Sent SMS log. content: application/json: schema: { type: object, additionalProperties: true } /gateway/mobile/list/: get: tags: [Devices] operationId: listConnectedMobiles summary: List connected mobile devices parameters: - name: sid in: query schema: { type: string } - name: search in: query schema: { type: string } responses: "200": description: Connected devices and status metadata. content: application/json: schema: { type: object, additionalProperties: true } /call/missed/list/: get: tags: [Calls] operationId: listMissedCalls summary: List missed calls parameters: - $ref: "#/components/parameters/Offset" - $ref: "#/components/parameters/Limit100" - $ref: "#/components/parameters/Search" - $ref: "#/components/parameters/DateStart" - $ref: "#/components/parameters/DateEnd" responses: "200": description: Missed calls from newest to oldest. content: application/json: schema: { $ref: "#/components/schemas/CallListResponse" } /call/incoming/list/: get: tags: [Calls] operationId: listIncomingCalls summary: List answered incoming calls parameters: - $ref: "#/components/parameters/Offset" - $ref: "#/components/parameters/Limit50" - name: q in: query schema: { type: string } description: Search phone number or cached contact name. - $ref: "#/components/parameters/SortDirection" responses: "200": description: Incoming call activity. content: application/json: schema: { $ref: "#/components/schemas/CallRowsResponse" } /call/outgoing/list/: get: tags: [Calls] operationId: listOutgoingCalls summary: List outgoing calls parameters: - $ref: "#/components/parameters/Offset" - $ref: "#/components/parameters/Limit50" - name: q in: query schema: { type: string } description: Search phone number or cached contact name. - $ref: "#/components/parameters/SortDirection" responses: "200": description: Outgoing call activity. content: application/json: schema: { $ref: "#/components/schemas/CallRowsResponse" } /notification/send: post: tags: [Notifications] operationId: sendNotification summary: Send an internal notification to a connected mobile requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object required: [apikey, sid, message] properties: apikey: { type: string } sid: { type: string } title: { type: string, default: Notification } message: { type: string } type: { type: string, default: notification } responses: "200": description: Notification created. content: application/json: schema: { $ref: "#/components/schemas/NotificationSendResponse" } /notification/list/: get: tags: [Notifications] operationId: listNotifications summary: List notification history parameters: - name: sidentifiant in: query schema: { type: string } - name: distribued in: query schema: { type: integer, enum: [0, 1] } - $ref: "#/components/parameters/DateStart" - $ref: "#/components/parameters/DateEnd" responses: "200": description: Notification distribution history. content: application/json: schema: { type: object, additionalProperties: true } /getwa/active/: get: tags: [WhatsApp] operationId: setWhatsAppRetrieval summary: Activate or deactivate WhatsApp message retrieval parameters: - name: statut in: query schema: { type: string, enum: ["0", "1", x], default: x } description: 1 activates, 0 deactivates, x toggles. responses: "200": description: Current retrieval state. content: application/json: schema: { type: object, additionalProperties: true } /getwa/synchronisation/: get: tags: [WhatsApp] operationId: requestWhatsAppSynchronization summary: Request a time-limited WhatsApp synchronization window description: Required before retrieving newly received WhatsApp messages. responses: "200": description: Synchronization requested. content: application/json: schema: { $ref: "#/components/schemas/WhatsAppSynchronizationResponse" } /getwa/: get: tags: [WhatsApp] operationId: listReceivedWhatsApp summary: Retrieve synchronized WhatsApp messages description: Activate retrieval and request synchronization before calling this endpoint. parameters: - name: before in: query schema: { type: integer } - name: date in: query schema: { type: string, format: date } - name: message_type in: query schema: { type: string, enum: [text, audio] } responses: "200": description: Recovered WhatsApp messages. content: application/json: schema: { type: object, additionalProperties: true } /whatsapp/checknumber/: get: tags: [WhatsApp] operationId: checkWhatsAppNumber summary: Check whether a number is available on WhatsApp parameters: - name: recipients in: query required: true schema: { type: string } description: Country code plus number, without + or 00. responses: "200": description: WhatsApp availability result. content: application/json: schema: { type: object, additionalProperties: true } /sendemail/: post: tags: [Email] operationId: sendEmail summary: Send e-mail through a configured mailbox requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object required: [apikey, apikeybox, sender_name, sender_email, recipient_email, mail_subject, mail_body, allow_self_signed] properties: apikey: { type: string } apikeybox: { type: string } sender_name: { type: string } sender_email: { type: string, format: email } recipient_email: { type: string, format: email } mail_subject: { type: string } mail_body: { type: string } allow_self_signed: { type: string, enum: ["yes", "no"] } unsubscribe: { type: integer, enum: [1] } attachmentBase64: { type: string, contentEncoding: base64 } attachmentBase64_name_1: { type: string } responses: "200": description: E-mail operation result. content: application/json: schema: { type: object, additionalProperties: true } /getemail/: get: tags: [Email] operationId: listEmails summary: Retrieve e-mail from a configured mailbox folder parameters: - name: apikeybox in: query required: true schema: { type: string } - name: mbox in: query required: true schema: { type: string, default: INBOX } - name: start in: query required: true schema: { type: integer, minimum: 0, default: 0 } responses: "200": description: Mailbox messages. content: application/json: schema: { type: object, additionalProperties: true } /telegram/contacts/: get: tags: [Telegram] operationId: listTelegramContacts summary: List contacts of the connected Telegram account description: Synchronize contacts in the dashboard first. Returns account-scoped contact IDs ordered oldest first. security: [{ ApiKeyHeader: [] }] parameters: - name: q in: query schema: { type: string, maxLength: 80 } description: Optional display-name or username search. - name: limit in: query schema: { type: integer, minimum: 1, maximum: 100, default: 50 } - name: cursor in: query schema: { type: integer, minimum: 0, default: 0 } description: paging.next_cursor returned by the previous page. responses: "200": description: Contact page. content: application/json: schema: { $ref: "#/components/schemas/TelegramContactsResponse" } "401": { $ref: "#/components/responses/Forbidden" } "403": { $ref: "#/components/responses/Forbidden" } "409": { $ref: "#/components/responses/BadRequest" } /telegram/send/: post: tags: [Telegram] operationId: sendTelegramMessage summary: Queue text, an image or a document to one Telegram contact description: | Send JSON text, JSON with file_base64 and filename, or multipart/form-data with a file field. Files must be 5 MB or smaller and use a supported JPG, PNG, WebP, PDF, TXT, CSV, JSON, ZIP or Office format. Text may contain up to 4096 characters; a file caption up to 1024. HTTP 202 means queued, not delivered. Repeating the same idempotency key and payload returns the original message ID with HTTP 200. A changed payload with the same key returns 409. security: [{ ApiKeyHeader: [] }] requestBody: required: true content: application/json: schema: type: object required: [contact_id] anyOf: - required: [message] - required: [filename, file_base64] properties: contact_id: { type: integer, minimum: 1 } message: { type: string, maxLength: 4096, description: Required for text-only sends; optional caption up to 1024 characters when a file is attached. } filename: { type: string, maxLength: 190, description: Required with file_base64. } file_base64: { type: string, contentEncoding: base64, description: Base64 file bytes, optionally as a data URI. Decoded size must not exceed 5 MB. } idempotency_key: { type: string, format: uuid, description: Reuse the same lowercase UUID and identical payload when retrying a network timeout. } examples: text: value: { contact_id: 42, message: "Your appointment is confirmed.", idempotency_key: "2d40bb10-cc42-4c30-a282-93fc6dd8e161" } image: value: { contact_id: 42, filename: "photo.png", file_base64: "BASE64_ENCODED_FILE", message: "See attached", idempotency_key: "2d40bb10-cc42-4c30-a282-93fc6dd8e161" } multipart/form-data: schema: type: object required: [contact_id, file] properties: contact_id: { type: integer, minimum: 1 } file: { type: string, format: binary, description: One supported image or document, up to 5 MB. } message: { type: string, maxLength: 1024, description: Optional caption. } idempotency_key: { type: string, format: uuid } responses: "202": description: Message queued for asynchronous sending. content: application/json: schema: { $ref: "#/components/schemas/TelegramSendResponse" } "200": description: Exact idempotent retry of an existing message. content: application/json: schema: { $ref: "#/components/schemas/TelegramSendResponse" } "400": { $ref: "#/components/responses/BadRequest" } "401": { $ref: "#/components/responses/Forbidden" } "402": { $ref: "#/components/responses/Forbidden" } "403": { $ref: "#/components/responses/Forbidden" } "409": { $ref: "#/components/responses/BadRequest" } "413": { $ref: "#/components/responses/BadRequest" } "415": { $ref: "#/components/responses/BadRequest" } "422": { $ref: "#/components/responses/BadRequest" } "429": { $ref: "#/components/responses/TooManyRequests" } "503": { $ref: "#/components/responses/BadRequest" } /telegram/sent/: get: tags: [Telegram] operationId: listTelegramSentMessages summary: List recent Telegram sends and their status description: Sent means Telegram accepted the message; delivery and read receipts are not available. security: [{ ApiKeyHeader: [] }] parameters: - name: message_id in: query schema: { type: integer, minimum: 1 } description: Exact message ID returned by the send endpoint. - name: contact_id in: query schema: { type: integer, minimum: 1 } description: Limit the log to one contact. - name: status in: query schema: { type: string, enum: [queued, sending, sent, error, unknown] } - name: limit in: query schema: { type: integer, minimum: 1, maximum: 100, default: 50 } - name: cursor in: query schema: { type: integer, minimum: 0, default: 0 } description: paging.next_cursor returned by the previous page. responses: "200": description: Message log page, newest first. content: application/json: schema: { $ref: "#/components/schemas/TelegramSentResponse" } "401": { $ref: "#/components/responses/Forbidden" } "402": { $ref: "#/components/responses/Forbidden" } "403": { $ref: "#/components/responses/Forbidden" } "409": { $ref: "#/components/responses/BadRequest" } /telegram/received/: get: tags: [Telegram] operationId: listTelegramReceivedMessages summary: List received private Telegram messages description: | Message reception is optional and off by default. Enable it in Dashboard → Telegram Connection before new private messages can be imported. Turning it off stops future imports; already stored messages remain available until the user clears the history. Self messages, groups, channels and messages from before the enabled period are excluded. Received image and file entries currently contain captions and metadata only; their bytes are not available for download. security: [{ ApiKeyHeader: [] }] parameters: - name: telegram_peer_id in: query schema: { type: integer, minimum: 1 } description: Optional private-chat peer filter. - name: limit in: query schema: { type: integer, minimum: 1, maximum: 100, default: 50 } - name: cursor in: query schema: { type: integer, minimum: 0, default: 0 } description: Use paging.next_cursor for the next page of older messages. responses: "200": description: Account-scoped received messages, newest first. content: application/json: schema: { $ref: "#/components/schemas/TelegramReceivedResponse" } "401": { $ref: "#/components/responses/Forbidden" } "402": { $ref: "#/components/responses/Forbidden" } "403": { $ref: "#/components/responses/Forbidden" } "409": { $ref: "#/components/responses/BadRequest" } "422": { $ref: "#/components/responses/BadRequest" } /telegram/media/: get: tags: [Telegram] operationId: downloadSentTelegramAttachment summary: Download a previously sent Telegram attachment description: | Use message_id with X-SMSMobileAPI-Key, or open the short-lived signed download_url returned by GET /telegram/sent/. Signed links expire after 15 minutes. Sent attachments are retained for up to 90 days. Received attachments are not downloadable here. security: [{ ApiKeyHeader: [] }, {}] parameters: - name: message_id in: query required: true schema: { type: integer, minimum: 1 } - name: expires in: query schema: { type: integer, minimum: 1 } description: Unix expiry timestamp from a signed download_url; use with signature instead of an API key. - name: signature in: query schema: { type: string } description: Signature from a signed download_url; use with expires instead of an API key. responses: "200": description: Binary image or document bytes. content: application/octet-stream: schema: { type: string, format: binary } "401": { $ref: "#/components/responses/Forbidden" } "402": { $ref: "#/components/responses/Forbidden" } "403": { $ref: "#/components/responses/Forbidden" } "404": { $ref: "#/components/responses/BadRequest" } "410": { $ref: "#/components/responses/BadRequest" } webhooks: mobileEvent: post: operationId: receiveMobileEventWebhook summary: SMSMobileAPI Webhook V2 delivery description: Verify the HMAC-SHA256 signature against the exact raw body and deduplicate the stable event ID. parameters: - name: X-SMSMobileAPI-Event in: header required: true description: Event type delivered by SMSMobileAPI. schema: type: string example: sms.received - name: X-SMSMobileAPI-Event-ID in: header required: true description: Stable delivery identifier supplied by SMSMobileAPI. Do not hard-code or reuse it. schema: type: string format: uuid example: "{{$guid}}" - name: X-SMSMobileAPI-Timestamp in: header required: true description: Unix timestamp used when verifying the webhook signature. schema: type: integer example: 1700000000 - name: X-SMSMobileAPI-Signature in: header required: true description: HMAC-SHA256 signature calculated by SMSMobileAPI for this delivery. schema: type: string pattern: "^v1=[a-f0-9]{64}$" example: "v1={{computed_hmac_sha256}}" - name: Idempotency-Key in: header required: true description: Stable idempotency identifier supplied for this delivery. Do not hard-code or reuse it. schema: type: string format: uuid example: "{{$guid}}" requestBody: required: true content: application/json: schema: { $ref: "#/components/schemas/WebhookEnvelope" } responses: "202": description: Event accepted for asynchronous processing. components: securitySchemes: ApiKeyQuery: type: apiKey in: query name: apikey ApiKeyHeader: type: apiKey in: header name: X-SMSMobileAPI-Key parameters: Offset: name: offset in: query schema: { type: integer, minimum: 0, default: 0 } Limit100: name: limit in: query schema: { type: integer, minimum: 1, maximum: 500, default: 100 } Limit50: name: limit in: query schema: { type: integer, minimum: 1, maximum: 200, default: 50 } Search: name: search in: query schema: { type: string } DateStart: name: date_start in: query schema: { type: string, format: date } DateEnd: name: date_end in: query schema: { type: string, format: date } AfterTimestamp: name: after_timestamp_unix in: query schema: { type: integer } SortDirection: name: sort_dir in: query schema: { type: string, enum: [asc, desc], default: desc } responses: BadRequest: description: Missing or invalid parameter. content: application/json: schema: { $ref: "#/components/schemas/ErrorResponse" } Forbidden: description: API key invalid, expired or unauthorized. content: application/json: schema: { $ref: "#/components/schemas/ErrorResponse" } TooManyRequests: description: Request rate is too high. headers: Retry-After: schema: { type: integer } content: application/json: schema: { $ref: "#/components/schemas/ErrorResponse" } schemas: TelegramPaging: type: object required: [has_more, next_cursor] properties: has_more: { type: boolean } next_cursor: { type: [integer, "null"] } TelegramContactsResponse: type: object required: [ok, data, paging] properties: ok: { type: boolean, const: true } data: type: array items: type: object required: [contact_id, display_name, username, source] properties: contact_id: { type: integer } display_name: { type: string } username: { type: [string, "null"] } source: { type: string } paging: { $ref: "#/components/schemas/TelegramPaging" } TelegramSendResponse: type: object required: [ok, message_id, status, idempotency_key, duplicate] properties: ok: { type: boolean, const: true } message_id: { type: integer } status: { type: string, enum: [queued, sending, sent, error, unknown] } idempotency_key: { type: string } duplicate: { type: boolean } TelegramSentResponse: type: object required: [ok, data, paging] properties: ok: { type: boolean, const: true } data: type: array items: type: object required: [message_id, contact_id, message, type, media, status, attempts, queued_at] properties: message_id: { type: integer } contact_id: { type: integer } contact_name: { type: [string, "null"] } username: { type: [string, "null"] } message: { type: string } type: { type: string, enum: [text, image, file] } media: oneOf: - type: "null" - $ref: "#/components/schemas/TelegramSentMedia" status: { type: string, enum: [queued, sending, sent, error, unknown] } telegram_message_id: { type: [integer, "null"] } error_code: { type: [string, "null"] } error_detail: { type: [string, "null"] } attempts: { type: integer } queued_at: { type: string, format: date-time } sent_at: { type: [string, "null"], format: date-time } paging: { $ref: "#/components/schemas/TelegramPaging" } TelegramSentMedia: type: object required: [type, filename, mime_type, size_bytes, download_url, available_until] properties: type: { type: string, enum: [image, document] } filename: { type: string } mime_type: { type: string } size_bytes: { type: integer, minimum: 0 } download_url: { type: [string, "null"], format: uri, description: Signed link valid for 15 minutes, or null when unavailable. } available_until: { type: [string, "null"], format: date-time } TelegramReceivedResponse: type: object required: [ok, data, paging] properties: ok: { type: boolean, const: true } data: type: array items: type: object required: [message_id, telegram_peer_id, telegram_message_id, telegram_sender_id, sender_name, username, message, type, media, received_at, captured_at] properties: message_id: { type: integer, description: SMSMobileAPI inbox ID used as the paging cursor. } telegram_peer_id: { type: integer } telegram_message_id: { type: integer } telegram_sender_id: { type: [integer, "null"] } sender_name: { type: string } username: { type: string } message: { type: string, description: Text or an attachment caption. } type: { type: string, enum: [text, image, file] } media: oneOf: - type: "null" - $ref: "#/components/schemas/TelegramReceivedMedia" received_at: { type: string, format: date-time } captured_at: { type: string, format: date-time } paging: { $ref: "#/components/schemas/TelegramPaging" } TelegramReceivedMedia: type: object required: [filename, mime_type, download_url] properties: filename: { type: string } mime_type: { type: string } download_url: { type: "null", description: Received attachment bytes are not retained in this release. } ErrorResponse: type: object additionalProperties: true properties: error: oneOf: [{ type: string }, { type: integer }] message: { type: string } SendMessageResponse: type: object additionalProperties: true properties: result: type: object additionalProperties: true properties: error: oneOf: [{ type: string }, { type: integer }] sent: { type: string } id: { type: string } note: { type: string } datetime: { type: string, format: date-time } send_with_whatsapp: { type: string } ReceivedSmsResponse: type: object additionalProperties: true properties: result: type: object additionalProperties: true properties: error: { type: string } sms: type: array items: type: object additionalProperties: true properties: id: { type: integer } sIdentifiantPhone: { type: string } timestamp_unix: { type: integer } message: { type: string } number: { type: string } guid: { type: string } alias: { type: [string, "null"] } CallListResponse: type: object additionalProperties: true properties: success: { type: boolean } offset: { type: integer } limit: { type: integer } count: { type: integer } data: type: array items: { $ref: "#/components/schemas/CallRecord" } CallRowsResponse: type: object additionalProperties: true properties: success: { type: boolean } count: { type: integer } rows: type: array items: { $ref: "#/components/schemas/CallRecord" } CallRecord: type: object additionalProperties: true properties: number: { type: string } phone_number: { type: string } name: { type: [string, "null"] } cached_name: { type: [string, "null"] } date: { type: string } call_datetime_utc: { type: string } duration_sec: { type: integer } NotificationSendResponse: type: object additionalProperties: true properties: success: { type: boolean } message: { type: string } id: { type: integer } apikey: { type: string } sid: { type: string } WhatsAppSynchronizationResponse: type: object additionalProperties: true properties: error: { type: string } messages: { type: string } expire_at: { type: string } expire_at_unix: { type: string } WebhookEnvelope: type: object required: [id, type, api_version, created_at, occurred_at, data] additionalProperties: false properties: id: type: string format: uuid description: Stable event identifier supplied by SMSMobileAPI. example: "{{$guid}}" type: type: string enum: - sms.api.submitted - sms.sent - sms.failed - sms.received - sms.mobile.sent - call.missed - call.incoming - call.outgoing - whatsapp.submitted - whatsapp.sent - whatsapp.failed - whatsapp.received - whatsapp.voice.transcribed - telegram.submitted - telegram.sent - telegram.failed - telegram.unknown - telegram.received - email.sent - email.received api_version: { type: string } created_at: { type: string, format: date-time } occurred_at: { type: string, format: date-time } data: type: object additionalProperties: true