​
Prerequisites

​
Sender ID registration

A Sender ID is what recipients see as the message sender on their devices. It can be a numeric (phone numbers) or alphanumeric (brand names) Sender IDs. Before you send an SMS message, register your Sender ID on the Wavix platform. Alphanumeric Sender ID:
  • Must be between 3 and 11 characters long.
  • Can contain uppercase and lowercase ASCII letters, digits, hyphen (-), plus (+), underscore (_), ampersand (&), and space.
  • Should not contain only digits.
Numeric Sender ID:
  • Must be an SMS-enabled DID on your account.
  • Third-party numbers and DIDs that do not support inbound SMS cannot be used as a Sender ID.
You can register Sender IDs in the Wavix portal or by using the API.

​
Register a Sender ID using the app

1

Access Sender ID registration

  1. Sign in to your Wavix account.
  2. In the top menu, select SMS → Sender IDs.
  3. Select Create new.
2

Select Sender ID type

  • Select Alphanumeric to use a brand or service name as your Sender ID.
  • Select Numeric to use a phone number as your Sender ID. Then select Next. Sender ID registration (type) screenshot
3

Select destination countries

Select your destination countries. Sender ID regulation varies by country and Sender ID type; some destinations may be unavailable. Then select Next.Sender ID registration (destinations) screenshot
4

Select use case

Select your use case for messaging. Options include Promotional, Transactional, or Authentication. Enter your Sender ID name, estimate your monthly message volume, and provide sample messages you plan to send. Then select Next.Sender ID registration (use case) screenshot
5

Summary and confirmation

Review the Sender ID, type, and destination countries. Your Sender ID will be automatically allow-listed for countries where no additional paperwork is required. Countries that require manual registration will be highlighted. Select Confirm. You can immediately start sending messages to countries that do not require manual Sender ID registration.

​
Register a Sender ID using the API

Sender ID regulations vary by country. You can register a Sender ID using the API only in countries that allow instant registration for the Sender ID type. If a country in the request doesn’t, the API returns the HTTP 400 Bad Request status code with an error message that names the country. In that case, create the Sender ID in the Wavix portal and go through the review or registration procedure. To register a new Sender ID, use the following method: 
POST https://api.wavix.com/v3/messages/sender-ids
Authorization: Bearer your_api_key
Content-Type: application/json
Paste the following JSON in the request body: 
{
    "sender_id": "Wavix",
    "type": "alphanumeric",
    "countries": [
        "GB",
        "FR"
    ],
    "usecase": "transactional",
    "monthly_volume": "1001-20000",
    "samples": [
        "Your order 12345 has shipped.",
        "Your appointment is confirmed for May 3 at 10:00."
    ]
}
  • sender_id: the name of the Sender ID. Required.
  • type: Sender ID type, either numeric or alphanumeric. Required.
  • countries: an array of 2-letter ISO codes of the countries the Sender ID needs to be registered in. Required.
  • usecase: the messaging use case. Can be transactional, promo, or authentication. Required.
  • monthly_volume: the estimated monthly message volume. Can be 1-1000, 1001-20000, 20001-50000, 50001-100000, or More than 100000. Optional.
  • samples: an array of sample messages you plan to send. Optional.
To send messages to US recipients, register your Sender ID with the 10DLC API instead. Registering a Sender ID incurs a recurring monthly fee, billed to your Wavix account balance.
If successful, the method returns the HTTP 201 Created status code. The response body contains the Sender ID details. 
{
   "id": "5108c63f-af4d-4852-88e0-ce06e82db5d3",
   "sender_id": "Wavix",
   "type": "alphanumeric",
   "allowlisted_in": [
       "GB",
       "FR"
   ],
   "usecase": "transactional",
   "samples": [
       "Your order 12345 has shipped.",
       "Your appointment is confirmed for May 3 at 10:00."
   ]
}
  • id: system-generated unique ID of the Sender ID
  • sender_id: name of the Sender ID
  • type: Sender ID type
  • allowlisted_in: an array of countries the Sender ID is automatically provisioned in
  • usecase: the messaging use case
  • samples: the sample messages submitted with the Sender ID

​
Get a list of Sender IDs on the account

To get a list of Sender IDs, use the following method. This method does not require any parameters. 
GET https://api.wavix.com/v3/messages/sender-ids
Authorization: Bearer your_api_key
If successful, the method returns the HTTP 200 OK status code. The response body contains an array of Sender IDs provisioned on the account and their details. 
{
   "items": [
       {
           "id": "5108c63f-af4d-4852-88e0-ce06e82db5d3",
           "allowlisted_in": [
               "GB",
               "FR"
           ],
           "sender_id": "Wavix",
           "type": "alphanumeric"
       },
       {
           "id": "94b319e0-8277-4efa-b7ec-d6e0e255ddaf",
           "allowlisted_in": [
               "US",
               "CA" 
           ],
           "sender_id": "1313xxxxxxx",
           "type": "numeric"
       }
   ]
}
  • id: unique ID of the Sender ID
  • allowlisted_in: an array of countries the Sender ID is automatically provisioned in
  • sender_id: the name of the Sender ID
  • type: Sender ID type

​
Delete a Sender ID

To delete a Sender ID, use the following method: 
DELETE https://api.wavix.com/v3/messages/sender-ids/{id}
Authorization: Bearer your_api_key
  • id: unique ID of the Sender ID
If successful, the method returns the HTTP 200 OK status code and a success indicator. 
{
    "success": true
}

​
Send a message

Using a sandbox account? A few rules apply to this request—see Sandbox. To send an SMS or MMS message, use the following method: 
POST https://api.wavix.com/v3/messages
Authorization: Bearer your_api_key
Content-Type: application/json
Paste the following JSON in the request body: 
{
   "from": "SenderID",
   "to": "1686xxxxxxx",
   "message_body": {
       "text": "Message text.",
       "media": ["https://publicly-available-resource.com/media"]
   }
}
  • from: the Sender ID to be used to send an SMS, must be a registered Sender ID on your account. Required.
  • to: the recipient phone number, must be in E.164 format (international format with + and country code, for example, +12015551234). Required.
  • message_body.text: the text of the SMS message to be sent. Required.
  • message_body.media: an array of up to 5 URLs to media files to be included in the message attachments. In case the parameter is specified and its value is different from null, the message will be sent as MMS. The URLs must point to publicly available resources. Optional.
You can also include these optional parameters:
  • callback_url: the URL where Wavix sends delivery reports for the message.
  • validity: the message validity period, in seconds. Delivery attempts stop after this period expires.
  • tag: a tag to group messages, such as for a specific campaign.
If successful, the service returns the HTTP 201 Created status code. The response body contains the sent message details. Response example: 
{
  "message_id": "871b4eeb-f798-4105-be23-32df9e991456",
  "message_type": "mms",
  "from": "13137890021",
  "to": "13137890021",
  "mcc": "301",
  "mnc": "204",
  "message_body": {
    "text": "This is an MT message",
    "media": ["https://publicly-available-resource.com"]
  },
  "tag": null,
  "status": "accepted",
  "segments": 1,
  "charge": "0.02",
  "carrier_fees": "0.003",
  "submitted_at": "2022-04-14T13:51:16.096Z",
  "sent_at": null,
  "delivered_at": null,
  "error_message": null
}

​
Get message details

To get the message details, including delivery status, use the following method: 
GET https://api.wavix.com/v3/messages/{message_id}
Authorization: Bearer your_api_key
  • message_id: the unique identifier of the message on the Wavix platform for which the details are requested.
If successful, the service returns the HTTP 200 OK status code. The response body contains the message details. Response example: 
{
  "direction": "outbound",
  "message_id": "871b4eeb-f798-4105-be23-32df9e991456",
  "message_type": "mms",
  "from": "13137890021",
  "to": "13137890021",
  "mcc": "301",
  "mnc": "204",
  "message_body": {
    "text": "This is an MT message",
    "media": ["https://publicly-available-resource.com"]
  },
  "tag": "1234",
  "status": "delivered",
  "segments": 1,
  "charge": "0.02",
  "submitted_at": "2022-04-14T13:51:16.096Z",
  "sent_at": "2022-04-14T13:51:16.096Z",
  "delivered_at": "2022-04-14T13:51:16.096Z",
  "error_message": null
}
For outbound messages, the status field shows the delivery status:
  • accepted: The Wavix platform accepted the message for sending
  • pending: The message is queued and awaiting a carrier response
  • sent: The message was handed to the carrier
  • delivered: The carrier confirmed delivery to the handset
  • undelivered: The carrier reported that delivery failed; check error_message for details
  • expired: The validity period elapsed before the message was sent
  • rejected: The message was rejected before sending; check error_message for details
  • dlr_expired: No delivery receipt arrived from the carrier within the expected window

​
Unsubscribe a recipient

If you need to unsubscribe a recipient from receiving SMS or MMS messages, use the following method: 
POST https://api.wavix.com/v3/messages/opt-outs
Authorization: Bearer your_api_key
Content-Type: application/json
Paste the following JSON in the request body: 
{
   "opt_out": {
       "number": "1686xxxxxxx",
       "sender_id": "1716xxxxxxx"
   }
}
  • opt_out.number: the phone number to be opted out. Required.
  • opt_out.sender_id: Sender ID of which the phone number will be opted out. If not specified, the phone number will be opted out of all SMS messages.
If successful, the service returns the HTTP 201 Created status code and a success indicator. 
{
   "success": true
}