SMS Documentation

Send SMS

Endpoint: 

Parameters:

Example:

Resend an unsent SMS

This API endpoint is used to resend an unsent SMS (only if the message has an error status).

Endpoint:

Parameter: 

Example: 

Log of SMS sent from the API

This API endpoint is used to retrieve the log of SMS messages sent via the API.

Endpoint: 

Parameter:

Example:

List sent SMS from mobile

This API endpoint is used to list SMS messages sent from your mobile device and synchronized to your SMSMobileAPI account.

Important: This feature is available starting from Android version 4.1.20.

Important: This feature is not enabled by default in the Android app.

Privacy: All synchronized information is anonymized, confidential, and handled securely.

History limit: This API always returns data from the last 7 days only.

Note: If you send SMS using the standard API endpoint https://api.smsmobileapi.com/sendsms/, these SMS may also appear in this listing because they are physically sent from your mobile device.

Endpoint:

Parameters: 

Returned fields: 

Example: 

Example with filters:

Example with predefined period:

SMS Received

This API endpoint is used to retrieve SMS messages received on the smartphone. 

Endpoint:

Parameter: 

Example:

Mark SMS Messages Received as Read

This API endpoint is used to mark one received SMS message as read in the API status only.
This does not change the read status on the smartphone.  

Endpoint:

Parameter: 

Example:

Update SMS alias

This API endpoint is used to update the alias of a received SMS using its GUID.

Note: The alias parameter can be empty. In that case, the alias will be cleared.

Endpoint:

Parameters: 

Example: 

Example to clear the alias:

Delete SMS

This API endpoint is used to delete SMS messages from the server log of SMS Mobile API.

Endpoint: 

Parameter:

Example:

Note: Deleted SMS are only those stored in server logs. SMS on the device will not be deleted.

List SMS conversations

This API endpoint is used to list SMS conversations linked to your account.

Each conversation is grouped by phone number and contains the related incoming and outgoing SMS messages.

Note: The conversation starting point is defined by the origineConversation parameter:

• received: conversations are first detected from received SMS in logsmsreceive
• sent: conversations are first detected from sent SMS in logsmssent

Note: If numero is not provided, the API returns the latest conversations only. By default, the last 20 conversations are returned.

Note: For outgoing SMS, if timearea_of_message is available (example: UTC+02), the displayed date is automatically converted using this value. This converted date is also used for sorting.

Note: If resume=1, only the latest messages of each conversation are returned. Use resume_line_how to define how many latest messages should be included.

Endpoint:

Parameters: 

Behavior details: 

Example 1 - List latest conversations from received SMS: 

Example 2 - List latest conversations from sent SMS:

Example 3 - Filter one specific phone number:

Example 4 - Filter by date range:

Example 5 - Resume mode with the last 3 messages per conversation:

Successful response example: 

{
  "success": true,
  "origineConversation": "received",
  "resume": 0,
  "resume_line_how": null,
  "conversations": [
    {
      "phone_number": "+10470000001",
      "contact_alias": "John Doe",
      "messages": [
        {
          "direction": "incoming",
          "message_id": "msg_1001",
          "date": "2026-03-13 08:45:12",
          "timestamp_utc": "2026-03-13T08:45:12Z",
          "message": "Hello, I would like more information.",
          "status": "received",
          "mobile_sid": "device_sid_1"
        },
        {
          "direction": "outgoing",
          "message_id": "msg_1002",
          "date": "2026-03-13 10:46:03",
          "timestamp_utc": "2026-03-13T08:46:03Z",
          "message": "Of course, what would you like to know?",
          "status": "sent",
          "mobile_sid": "device_sid_2"
        }
      ]
    }
  ]
}

Response fields:

Error example:

{
  "success": false,
  "error": "Missing required parameter: apikey"
}

Notes:

Gateway – List connected mobiles

List mobiles connected to your SMS Gateway.

Endpoint:

Parameters:

Example:

Gateway – Update a mobile label

Update the label (nom_reference) of a connected mobile.

Endpoint:

Parameters:

Example:

Important: label is required but can be empty (label=).

Gateway – Delete a connected mobile

Remove a connected mobile from your gateway (deletes all history rows for this SID).

Endpoint:

Parameters:

Example:

Webhook – SMS Received

This webhook system sends a POST request to the configured URL whenever an SMS is received. The system ensures real-time updates by delivering the SMS details to the specified webhook URL.

How to Configure the Webhook in the Dashboard

Follow these steps to set up your webhook URL in the dashboard:

1. Log in to your account on the SMS Mobile API Dashboard.
2. Navigate to the Webhook Settings section.
3. Enter your webhook URL (e.g., https://example.com/webhook-endpoint).
4. Click on the Save Webhook button. 
5. Once saved, the system will start sending SMS details to the configured URL.

Webhook Payload

When an SMS is received, the system sends the following JSON payload to your webhook URL:

{
    "date": "2025-01-20",
    "hour": "10:15:00",
    "time_received": "2025-01-20 10:14:50",
    "message": "Hello, this is a test.",
    "number": "+123456789",
    "guid": "abcde12345"
}

Payload Fields:

• date: Date when the SMS was added (YYYY-MM-DD).
• hour: Hour when the SMS was added (HH:mm:ss).
• time_received: Time when the SMS was received.
• message: Content of the SMS. 
• number: Sender's phone number.
• guid: Unique identifier of the SMS.

Example Webhook Endpoint

Your server should be ready to handle incoming POST requests. Below is an example PHP script to process the webhook payload:

<?php
$payload = file_get_contents('php://input');
$data = json_decode($payload, true);

if ($data) {
    file_put_contents('sms_log.txt', print_r($data, true), FILE_APPEND);
    http_response_code(200);
    echo "Webhook received successfully.";
} else {
    http_response_code(400);
    echo "Invalid payload.";
}
?>

Testing the Webhook

To test your webhook configuration, use tools like:

• Webhook.site
• RequestBin

Troubleshooting

• Ensure the webhook URL is correct and publicly accessible.
• Verify that your server is returning an HTTP 200 status code for successful requests.
• Check your server logs for any errors in processing the payload.

Enriched SMS

Authentication

The SMSMobile API supports two authentication methods: using a simple API Key or the OAuth2 protocol with a client ID and client secret.

1. API Key Authentication

 This method requires an API Key that can be included as a parameter in either a GET or POST request.

2. OAuth2 Authentication

OAuth2 provides a more secure authentication method.
Use a client ID and client secret to obtain an access token, then include it in the Authorization header.

The client_id and client_secret are available in your dashboard.
Download the mobile app now or access your dashboard.

Obtaining an Access Token

Using the Access Token:

Which Method Should You Use?

- Use API Key Authentication for quick and straightforward integrations.

- Use OAuth2 Authentication for enhanced security and scalability.