📱 Webhook API Documentation

Send templated SMS & MMS via APImobile.digital

🚀 Quick Setup Guide

What is sendTemplatedEvent?
Templated SMS/MMS are pre-configured in the intouch portal (intouch Triggers) with all personalized tags predetermined. All you need is the tags and event name to trigger the pre-configured template.

Step-by-Step Setup

  1. Create Trigger Template in intouch Portal
    Log in to intouch and create your SMS/MMS template with personalized tags (e.g., {firstname}, {code}, {url})
  2. Get Your API Credentials
    You'll need: x-api-key, merchant_id, and your event_name from intouch Triggers
  3. Choose Your Endpoint
    SANDBOX for testing
    PRODUCTION when ready to go live
  4. Make Your First API Call
    Send a POST request with your template data (see examples below)
  5. Monitor & Debug
    Check intouch portal for delivery status and logs

📬 sendTemplatedEvent Endpoint

PRODUCTION Live Resource URL

Use this when initial config and tests are complete

POST https://vyknnvnab2.execute-api.ap-southeast-2.amazonaws.com/prod/wbk-m0b1ledigital

SANDBOX Testing Resource URL

Use this endpoint when testing code config

POST https://vyknnvnab2.execute-api.ap-southeast-2.amazonaws.com/sandbox/wbk-m0b1ledigital

Event Types

Event Type Description Use Case
SMS Templated or event SMS send Text messages up to 306 characters (concatenated)
MMS Templated or event MMS send Messages with images/media (max 300KB)
SMSD Direct SMS send (no template) Simple SMS without pre-configured template
⚠️ Important Limits:
SMS: 160 characters per segment, up to 306 characters total (concatenated)
MMS: Packet must be under 300KB
• Messages are charged per 160-character slot

🔌 API Endpoints

OAuth2 Bearer API Endpoints

For direct SMS/MMS sending via OAuth2 authentication, use these endpoints:

Base URL

https://ah1ta9hc59.execute-api.ap-southeast-2.amazonaws.com/prod
Endpoint Method Description
/sendSMS POST Direct send SMS
/sendMMS POST Direct send MMS message
/sendTemplatedEvent POST Use saved triggers from intouch (intouch Triggers)
/test-oauth2 POST Test OAuth2 Bearer token authentication

Authentication Methods

Method Header Use Case
Webhook (x-api-key) x-api-key: your_api_key Webhook endpoints, simple authentication
OAuth2 Bearer Authorization: Bearer your_token OAuth2 API endpoints, more secure

📋 Request Parameters

Header Parameters

Parameter Description Required
x-api-key Authenticator header to validate request REQUIRED
Content-Type Must be application/json REQUIRED

Required Body Parameters

Parameter Type Description
event_type String "SMS" or "MMS" - Determines API call type via webhook
event_name String Event name identified in intouch Triggers (unique, alphanumeric)
from String Dedicated Virtual Number (for opt-outs and two-way management)
recipient Numeric Mobile number of recipient (numeric characters only)
tracking_id String Unique number to track SMS transactions (alphanumeric)
merchant_id Numeric Your unique client number for authorization

Optional Parameters

Parameter Type Description
firstname String Recipient first name (alphanumeric)
surname String Recipient surname (alphanumeric)
fullname String Full name - will be split into first and last word
email Email Recipient email (must be valid email format)
code String Recipient code assigned
pin Numeric Code PIN if present
value String Code value (for code pool)
url String Your code URL if mapped
tracker_link String intouch shortened URL (pass encoded URL for click.link service)
pass_config_id String Wallet pass config ID (contact admin if unknown)
marketing_message String Marketing message content
personal_message String Personal message content
title String Message title
subject String Message subject
tc String Terms and Conditions
expiry_date Date Expiry date (default format: dd/mm/yyyy)
store_name String Additional store or brand name
custom_1 String First custom field
custom_2 String Second custom field
custom_3 String Third custom field
trailing_sms String ⚠️ Overwrites templated content - use only if override required
💡 Tip: Optional parameters are only needed if they are mapped in your intouch template or part of personalized image tags.

💻 Code Examples

Complete Request Example (JSON)

POST /prod/wbk-m0b1ledigital HTTP/1.1
Host: vyknnvnab2.execute-api.ap-southeast-2.amazonaws.com
Content-Type: application/json
x-api-key: your_api_key_here

{
  "recipient": "61412345678",
  "event_name": "WelcomeMessage",
  "event_type": "SMS",
  "tracking_id": "TXN-12345-67890",
  "merchant_id": "76",
  "customerId": "CUST-001",
  "system_internal_reference": "CRM-ID-123",
  "delay": 0,
  "optionParam": {
    "firstname": "John",
    "surname": "Smith",
    "fullname": "John Smith",
    "email": "john@mobile.digital",
    "code": "RQHWV3L6T3066",
    "pin": "1234",
    "value": "20",
    "url": "https://example.com/redeem",
    "tracker_link": "https://example.com/track",
    "marketing_message": "Special offer just for you!",
    "personal_message": "Thanks for being a valued customer",
    "title": "Welcome Gift",
    "subject": "Your Gift Card",
    "tc": "Terms apply. Valid 12 months.",
    "expiry_date": "31/12/2025",
    "store_name": "MyStore",
    "custom_1": "VIP",
    "custom_2": "Gold Member"
  }
}

PHP Example using cURL

<?php

// Initialize cURL
$curl = curl_init();

// Set cURL options
curl_setopt_array($curl, array(
  CURLOPT_URL => "https://vyknnvnab2.execute-api.ap-southeast-2.amazonaws.com/prod/wbk-m0b1ledigital",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode(array(
    "from" => "61428094360",
    "recipient" => "61412345678",
    "event_name" => "WelcomeMessage",
    "event_type" => "SMS",
    "tracking_id" => "TXN-".time(),
    "merchant_id" => "76",
    "optionParam" => array(
      "firstname" => "John",
      "email" => "john@example.com",
      "code" => "GIFT123"
    )
  )),
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "x-api-key: your_api_key_here"
  ),
));

// Execute request
$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

// Handle response
if ($err) {
  echo "cURL Error: " . $err;
} else {
  echo $response;
}

?>

Direct SMS Send (SMSD) - Simpler Example

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://vyknnvnab2.execute-api.ap-southeast-2.amazonaws.com/prod/wbk-m0b1ledigital",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode(array(
    "from" => "61428094360",
    "recipient" => "61412345678",
    "trailing_sms" => "Hello! This is a test message.",
    "tracking_id" => "TXN-".time(),
    "merchant_id" => "76",
    "event_type" => "SMSD"
  )),
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "x-api-key: your_api_key_here"
  ),
));

$response = curl_exec($curl);
curl_close($curl);

echo $response;

✅ API Response

Success Response

{
  "code": "200",
  "response": "success"
}

Response Status Codes

Code Status Description
200 Success Request processed successfully
400 Error Bad Request - Invalid parameters or missing required fields
401 Error Unauthorized - Invalid or missing x-api-key
403 Error Forbidden - Insufficient permissions
500 Error Internal Server Error - Contact support
✅ Best Practices:
• Always check the response code before proceeding
• Store tracking_id for later reference and debugging
• Monitor delivery status in intouch portal
• Use sandbox endpoint for all testing