Developer Guide: Sending International SMS with Templates

This guide provides a comprehensive walkthrough for integrating our International SMS API into your application. To ensure maximum deliverability and compliance with global carrier regulations, our platform uses a template based system. This means you must use an approved message template before sending SMS messages.

This tutorial will cover the entire workflow from checking available templates to sending a message.

The Core Workflow: A Template First Approach

Sending an international SMS is a two stage process. First, you identify an approved template that fits your needs. Second, you use that template's ID to send the message to your users. This ensures your content is pre-vetted for compliance, which drastically improves sending success rates.

Step 1: Find an Approved Template

To begin, you need to retrieve the list of all available templates to find one that is approved and suits your purpose. Our platform comes with several default templates, and you can also submit your own.

Note: This is a free administrative call and does not count towards your usage quota.

The Endpoint Use the GET /international-sms/v1/templates endpoint.

The Process Make a simple GET request with your API key to see all your templates and their current status.

curl "https://hub.juheapi.com/international-sms/v1/templates?apikey=YOUR_API_KEY"

The API will return a list of your templates. Each template object includes a state field, which indicates its approval status.

• 0: Waiting
• 1: Rejected
• 2: Pending
• 3: Approved

You must use a template with a state of 3 (Approved). Find the one you want to use and note its tplId.

Step 2 (Optional): Submit a Custom SMS Template

If none of the default templates meet your needs, you can submit a custom one for approval.

Note: This is a free administrative call and does not count towards your usage quota.

The Endpoint You will use the GET /international-sms/v1/submit_tpl endpoint.

The Process To submit a template, you need to provide your signature and the message content.

• Signature: A unique identifier for your business, like your company name. For example, JuheTech.
• Content: The body of your message. Use hashtags to define variables. For example, Your verification code is #code#. It is valid for #expire# minutes.

Here is an example API call:

curl "https://hub.juheapi.com/international-sms/v1/submit_tpl?apikey=YOUR_API_KEY&signature=JuheTech&content=Your verification code is #code#. It is valid for #expire# minutes."

Upon successful submission, the API will return a tplId. You must wait for this template's state to become 3 before you can use it.

Step 3: Send the SMS Using Your Template

With an approved tplId, you are now ready to send messages to your users.

The Endpoint Use the POST /international-sms/v1/send endpoint.

The Process In your POST request, you will need to specify the recipient's phone number (mobile), the template ID (tpl_id), and the values for the variables in your template (tpl_value).

The tpl_value parameter must be formatted as a single string, similar to a URL query string, where each variable is defined and pairs are separated by an ampersand (&).

Format: #variable1#=value1&#variable2#=value2

Here is a conceptual request body showing the correct structure:

// POST Request Body to /international-sms/v1/send
{
  "phone": "747****832",
  "area_code": "44",
  "tpl_id": "13100",
  "tpl_value": "#code#=345678&#minutes#=5",
  "sign": "Custom Support"
}

This call will correctly interpret the tpl_value string and send the message "Your verification code is 345678. It is valid for 5 minutes." to the specified phone number.

Reference: Checking Country Support

Before attempting to send an SMS, you can verify if we support the destination country or area.

Note: This is a free administrative call and does not count towards your usage quota.

The Endpoint Use the GET /international-sms/v1/area_code endpoint.

The Process This request will return a complete list of all supported countries and their corresponding area codes.

curl "https://hub.juheapi.com/international-sms/v1/area_code?apikey=YOUR_API_KEY"

Review this list to ensure your target countries are included.

Conclusion

By following this template first workflow, you ensure your application's SMS communications are reliable, compliant, and have the highest possible chance of successful delivery. This structured approach is key to building a robust global messaging feature.