ReplyPath API (1.0.0)

The Replypath API enables you to send SMS messages and track individual responses. It provides a unique ReplyPath number for each outgoing message, allowing recipients to reply directly. These replies are then correlated with the original message and can be delivered to your system via callbacks.

• ReplyPath Number: A unique phone number allocated from a pool, used as the sender ID for an outgoing SMS. Replies to this number are routed back to your application.
• One-Shot Messages: A ReplyPath number can be configured as "one-shot," meaning it's released (and the original message record deleted) after the first reply is received. This is useful for transactional messages where only a single response is expected.
• Callbacks: Your system can receive incoming MO (Mobile Originated) SMS messages by configuring a replypath callback URL. The API will send the message details to this URL either via GET or POST request, depending on the configured protocol.
• DLR (Delivery Receipt): A delivery receipt is sent to the callback URL configured for the account when the SMS has been successfully delivered to the recipient's phone.
• Validity Period (VP): Determines how long an allocated ReplyPath number remains active and how long the network will attempt to deliver the SMS. Replies can only be received during this period.

• Send individual SMS messages.
• Receive replies to sent messages via unique ReplyPath numbers.
• Webhook/callback integration for incoming MO SMS.
• Configurable validity period for ReplyPath numbers.
• "One-shot" message support for single-reply scenarios.
• Automatic management of a pool of ReplyPath numbers.
• Basic Authentication for secure API access.

1. Send SMS: Your application makes a POST request to the replypath/v1/sendsms endpoint with the message details, recipient(s), and desired validity period.
2. ReplyPath Allocation: The API allocates a unique ReplyPath number from its pool for the specified validity period.
3. SMS Delivery: The SMS is sent to the recipient(s) with the ReplyPath number as the sender ID.
4. Delivery Report: If DLR is requested, and a DLR callback is configured for the account, the Spirius message server sends a delivery report to the configured callback URL.
5. Recipient Replies: The recipient replies to the SMS. The reply is sent to the ReplyPath number.
6. MO SMS Processing: The API receives the MO SMS.
   • It identifies the original MT (Mobile Terminated) message and associated account based on the ReplyPath number.
   • The MO SMS is stored.
7. Callback Delivery: If a callback URL is configured for the account, the API sends the MO SMS details to your URL via a GET or POST request, depending on the configured protocol.
8. One-Shot Cleanup: If the original message was "one-shot," the ReplyPath number is released, and the original sent message record is deleted after the first reply is processed.

Use Case Example

1. You send the question What time are you coming? to mobile user +46123456789.
2. You get transaction-id {1} in return from the Smart Replypath API.
3. You send another question What time does the game start? to the same mobile user.
4. You get transaction-id {2} in return from the Smart Replypath API.
5. The mobile user replies to one of the questions with the text At 10:30.
6. You get the message At 10:30 received in response to {1} from the Smart Replypath application.

This functionality is achieved by using a unique phone number as sender for each question. When the user responds to a question, the reply can be mapped to the question using the unique phone number.

The mapping for the unique numbers will be kept for a limited time only, this time is called the Validity Period (VP). The default VP value is three days. Any response coming in after the VP has expired will not be forwarded.

Because Smart Replypath require functionality provided by Extended Virtual Numbers, it will only work within Sweden which is the only country where the mobile phone networks are configured to allow extension digits to be added to a mobile phone number.

• 200 OK: Used for successful GET requests and synchronous operations.
• 400 Bad Request: Malformed request syntax, invalid request message framing, or deceptive request routing. Also used for validation failures (e.g., invalid parameters, missing required fields).
• 401 Unauthorized: Authentication failure. Client lacks valid credentials.
• 403 Forbidden: Authenticated client does not have permission to access the requested resource.
• 429 Too Many Requests: Rate limit exceeded.
• 500 Internal Server Error: A generic error message, given when an unexpected condition was encountered and no more specific message is suitable.
• 503 Service Unavailable: The server is currently unable to handle the request due to a temporary overload or maintenance of the server.

Authorization

Basic auth with SMS account username and password.

Authorization: Basic <base64_encoded_username:password>

Content-Type

Content-Type should be application/json.

Content-Type: application/json

SMS Message Length

• A single SMS can contain a maximum of 160 characters if it only uses characters from the GSM-7 character set. If it contains any characters not in GSM-7 (e.g., emojis, accented characters), it's treated as Unicode (UCS-2), and the limit becomes 70 characters per SMS part.
• When sending longer messages, the message is split into multiple parts (concatenated SMS). Up to 10 SMS parts can be concatenated.
• Due to concatenation headers, the character limit per part is reduced to 153 for GSM-7 and 67 for Unicode.
• Messages exceeding the total limit (e.g., >10 parts) will be rejected.
• Messages must be between 1 and 1530 characters in length.

Rate Limits

• Configured per account, up to a maximum of 100 r/s. Check your account details.
• Exceeding the rate limit will result in 429 Too Many Requests errors.

Character Encoding

• The API expects request bodies (JSON) to be UTF-8 encoded.
• SMS message content (Msg field) will be processed to automatically determine if it's GSM-7 or Unicode for sending.

Phone Number Format

The API will normalize the phone number to a standard format, removing any non-digit characters and ensuring a consistent format, however the recommended format is international with a leading + (E.164)

• Accepted international formats should have a leading + or 00, e.g. +46123456789 or 0046123456789
• Accepted national formats starts with 0, e.g. 0701234567. If national format is used, the API assumes that the number is Swedish

• Sent Messages (MT): Stored for the duration of their validity_period (VP) or until a reply is received if one_shot is true. The VP determines how long the ReplyPath number is active.
• Received Messages (MO): Stored and linked to the original MT message. They expire when the original MT message's validity_period ends.
• Default Validity Period: The default VP is 3 days if not specified by the client. This is also the maximum configurable period. Clients can specify shorter VPs.
• OneShot Behavior: If one_shot is true for a sent message:
  • The ReplyPath number reservation and the sent message record are deleted from the system after the first MO reply associated with that MT message is successfully processed (including callback attempt).
  • Subsequent replies to that (now-deleted) ReplyPath number reservation will not be processed or linked.

• The API will send the MO SMS details to the callback URL configured for the account.
• The callback URL should be a valid HTTP or HTTPS URL.
• The API will send the MO SMS details to the callback URL via a GET or POST request, depending on the configured protocol.
• The callback URL should be able to handle the MO SMS details in JSON format.

If the delivery of the reply message to the callback URL fails, the API will attempt to resend the message to the callback URL. The resend attempts will continue regularly until the message is successfully delivered or the message record is deleted (after Validity Period has expired).

HTTP GET Example

127.0.0.1 - - [15/Sep/2016 20:31:45] "GET /reply?Msg=Ja+tack&InResponseTo=2531e755-71d0-4449-bb0c-e5657d13c570

HTTP POST Example

127.0.0.1 - - [15/Sep/2025 20:59:10] "POST /reply HTTP/1.1" 200 -
{
    "From": "+46123456789",
    "InResponseTo": "21d318ca-6598-4e3a-9212-f6b8ab5e79ae",
    "Msg": "Ja tack"
}

• The API uses standard HTTP status codes to indicate success or failure.
• Error responses are in JSON format and include a code and an error message and optionally a details object.
• Example:

  {
      "code": "VALIDATION_ERROR",
      "message": "Field required",
      "details": {
          "loc": ["body", "To"],
          "msg": "Field required",
          "type": "missing"
      }
  }
  

API health check endpoints.