Guide of Sending Global SMS

sms-live-demo

Guide of Sending Global SMS

This guide will walk you through the entire process of using a typical international SMS API, using the provided documentation as our example. We'll cover everything from creating and approving your message templates to making the final API call to send your first SMS.

The Workflow: A Quick Overview

Before diving into the details, let's look at the high-level process. Sending an SMS with this type of service involves three main stages:

Prepare a Template: All messages are based on a pre-defined template that must be approved by the service provider. This ensures compliance and deliverability.
Gather Your Parameters: Collect all the necessary information for the API call, such as the recipient's number, your API key, and the values for your template variables.
Make the API Call: Execute a POST request to the send endpoint with all your parameters correctly formatted.

Step 1: Crafting and Submitting Your SMS Template

The foundation of this system is the template. You can't send arbitrary text; you must first define a structure with fixed text and dynamic placeholders called variables.

Why Templates?

Security & Compliance: Providers review templates to prevent spam and ensure content complies with carrier policies.
Consistency: Guarantees a consistent message format for your users.
Reusability: Simplifies the sending process, as you only need to supply the variable data for each message.

How to Create a Template

You would use the GET /international-sms/v1/submit_tpl endpoint to submit your content for approval. A template consists of:

Content: The body of the message, with variables denoted by hashtags (e.g., #code#).
Signature: A brand name or identifier (e.g., "Juhe").

Looking at the example UI, we see an approved template:

ID: 13100
Content: Your sign-in verification code is #code#. The code will remain active for #expire# minutes.
Status: Approved

Only templates with an "Approved" status can be used to send messages.

Step 2: Sending the SMS via API

With an approved template, you're ready to send messages using the core endpoint: POST /international-sms/v1/send.

This endpoint requires the following query parameters:

Parameter	Type	Description	Example
`apikey`	string	Your unique API key for authentication.	`YOUR_API_KEY`
`area_code`	integer	The recipient's country code without the `+`.	`1` (for USA)
`phone`	string	The recipient's phone number without the country code.	`1234567890`
`tpl_id`	string	The ID of your approved template.	`13100`
`sign`	string	The SMS signature. This can often override the default.	`Custom Support`
`tpl_value`	string	The dynamic values for your template's variables.	`#code#=123456&#expire#=5`

Pro Tip: A Common Pitfall

Pay close attention to your variable names! In the example UI, the template content clearly defines the variable as #expire#. However, the example Template Values field shows #minutes#=5. This is a frequent source of errors.

Always ensure the variable names in your tpl_value parameter exactly match the variable names defined in your approved template content. In this case, the correct value should be #code#=123456&#expire#=5.

Live Demo: A `curl` Request Example

Let's put it all together. Here is a curl command that demonstrates how to send the verification SMS shown in the UI.

Bash

curl -X POST \ 'https://api.example.com/international-sms/v1/send?apikey=YOUR_API_KEY&area_code=1&phone=1234567890&tpl_id=13100&sign=Custom%20Support&tpl_value=%23code%23%3D123456%26%23expire%23%3D5'

URL Encoding: Don't Forget the Details!

Notice the strange characters like %23 and %26 in the tpl_value parameter. When you send data in a URL query string, special characters must be URL-encoded.

# becomes %23
& becomes %26
= becomes %3D
(space) becomes %20

Most modern HTTP clients and programming languages handle this automatically, but it's crucial to be aware of when debugging.

Decoding the API Response

After making the request, you'll receive a JSON response.

On Success, the API will echo back the parameters of the message sent:JSON

{ "phone": "747****832", "area_code": 44, "tpl_id": "13100", "tpl_value": "#code#=123456&#minutes#=5", "sign": "Custom Support" }
On Failure, you'll receive an error code and message to help you debug:JSON

{ "code": "string", "msg": "string" }

Useful Helper Endpoints

To make integration smoother, the API also provides helper endpoints:

GET /international-sms/v1/templates: Retrieve a list of all your available, approved templates and their IDs.
GET /international-sms/v1/area_code: Get a list of all supported countries and their area codes.

Key Takeaways

Integrating an international SMS API is straightforward when you follow the correct procedure. Remember these key points:

Templates First: All message content must be defined in an approved template.
Match Your Variables: Ensure the variables in your tpl_value string perfectly match those in the template.
URL-Encode Your Parameters: Correctly encode special characters in the query string.
Always Authenticate: Every API call requires your valid apikey.

By following these steps, you can reliably integrate international SMS capabilities into your application, enhancing user communication and engagement across the globe.

Guide of Sending Global SMS