Skip to main content

​
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 where it can be provisioned in self-service mode. To check if a numeric or alphanumeric Sender ID can be registered in self-service mode for a particular country, use: 
GET https://api.wavix.com/v3/messages/sender_ids/restrictions?country=country_code&type=sender_type
Authorization: Bearer your_api_key
  • country_code: 2-letter ISO code of the country
  • sender_type: Sender ID type, can be either numeric or alphanumeric
All parameters are required. If successful, the method returns the HTTP 200 OK status code. The response body indicates if a numeric or an alphanumeric Sender ID can be registered in self-service mode in the country. 
{
    "self_service": true
}
If the self_service attribute value is true, the Sender ID can be registered using the API. Otherwise, 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": "1313xxxxxxx",
    "countries": [
        "US"
    ],
    "type": "numeric"
}
  • sender_id: the name of the Sender ID
  • countries: an array of countries the Sender ID needs to be registered in
  • type: Sender ID type
If successful, the method returns the HTTP 200 OK status code. The response body contains the Sender ID details. 
{
   "id": "94b319e0-8277-4efa-b7ec-d6e0e255ddaf",
   "allowlisted_in": [
       "US"
   ],
   "sender_id": "1313xxxxxxx",
   "type": "numeric"
}
  • id: system-generated unique ID of the Sender ID
  • allowlisted_in: an array of countries the Sender ID is automatically provisioned in
  • sender_id: name of the Sender ID
  • type: sender ID type

​
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
Content-Type: application/json
  • id: unique ID of the Sender ID
If successful, the method returns the HTTP 204 No Content status code without the response body.

​
Send a message

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.
  • to: the recipient phone number, must be in E.164 format (international format with + and country code, e.g., +12015551234).
  • message_body.text: the text of the SMS message to be sent.
  • message_body.media: an array of 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.
All parameters are required. 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",
  "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: 
{
  "message": {
    "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: Message queued for delivery
  • sent: Message delivered to carrier
  • delivered: Delivery confirmed by recipient’s network
  • failed: Delivery failed; check error_message for details

​
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: 
{
   "sender_id": "1716xxxxxxx",
   "phone_number": "1686xxxxxxx"
}
  • 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.
  • phone_number: the phone number to be opted out
If successful, the service returns the HTTP 204 No Content status code.