WhatsApp Messaging with Advantus

WhatsApp serves as the primary communication channel that businesses can leverage to strengthen their audience reach.

Advantus takes it a step further by enabling you to send bulk messages to the right audience with WhatsApp notifications. With the Advantus App, you leverage hyper-personalisation in real-time by sending recommendations based on their preferences, activities and purchase history.

A significant advantage of the Advantus App is that it enables you to create highly customised experiences for each user. Moreover, it provides you with key insights into your messages, helping you improve your messaging campaigns and build strong relationships with users.

Pre-Requisites to Use WhatsApp API

To leverage the WhatsApp API to send messages via Advantus, you need:

1. Meta Developer Account

A Meta Developer Account refers to an account that developers create on the Meta (formerly Facebook) platform. It enables them to access developer tools, resources, and documentation for building applications and integrating with Meta's ecosystem.

If you don't have the Meta developer's account, register here or contact us for any query.

2. WhatsApp Business Account

A WhatsApp Business Account is an account specifically for businesses to communicate with customers on WhatsApp. It offers features like business profiles and tools for better customer interaction.

If you don't have a WhatsApp business account, create here or contact us for any query.

Method Type and API End Point

The Method Type and API Endpoint are as follows:

POST: /api/notifications/whatsapp

The Header for WhatsApp sending is:


{

"Authorization": "YOUR_TOKEN_HERE"

}

API request

To send a request to the API, the following parameters must be included in the payload.

Item	Data Type	Description	Required
campaign_name	`string`	A friendly name to identify your campaign (e.g., "Welcome Message", "December Promotion")	No
message_type	`string`	Currently only supports "template" as WhatsApp requires pre-approved messages	Yes
template_name	`string`	The name of your pre-approved WhatsApp template from your Business Account	Yes
template_language	`string`	Should be an ISO-certified language code. Language code for your template (e.g., "en", "es"). Must match your approved template language	Yes
segment_uuid	`string`	UUID of your saved audience segment. Use `segment_uuid` OR `receiver`, not both	Yes (if `receiver` not provided)
receiver	`array[string]`	List of recipient phone numbers with country codes (e.g., "912345678999") Note: Leverage `segment_uuid` for scenarios with multiple recipients.	Yes (if `segment_uuid` not provided)
mapper_fields¹	`object`	It enables the senders to use variables² through a template or auidence segment. These variables can be used for hyper-personalisation when sending a message using Advantus.	Yes³
type	`integer`	Type defines the nature of the value. If the `type` is 0 then the value will be taken from audience segment. If the `type` is 1 then the value will be taken from `value`.	Yes
value	`string`	The variable value defined in the `type` 0 (audience segment) or `type` 1 (text).	Yes
sub_type	`string`	Variables defined in the template for `header`, and `button`.	Yes
mapper_fields.header.n	`object`	Values for header variable. Only one variable allowed. n is the variable number	Yes (if header has variables)
mapper_fields.header.n.type	`integer`	Use 1 for direct value, 0 for audience segment value	Yes (if using header)
mapper_fields.header.n.sub_type	`string`	Either text or media. When selecting media, can add any of these: Image, video, document⁴, or location.	Yes (if using header)
mapper_fields.header.n.value	`string`	The actual content to replace the variable with	Yes (if using header)
mapper_fields.body.n	`object`	Values for body variables. Can have multiple. n is the variable number	Yes (if body has variables)
mapper_fields.body.n.type	`integer`	Use 1 for direct value, 0 for audience segment value	Yes (if using body variables)
mapper_fields.body.n.value	`string`	The actual content to replace the variable with.	Yes (if using body variables)
mapper_fields.button.n	`object`	Button variable values. Maximum 2 buttons. n is the variable number	Yes (if buttons have variables)
mapper_fields.button.n.type	`integer`	Use 1 for direct value, 0 for audience segment value	Yes (if using buttons)
mapper_fields.button.n.sub_type	`string`	"url" for links or "coupon_code" for copyable codes	Yes (if using buttons)
mapper_fields.button.n.value	`string`	The URL or coupon code	Yes (if using buttons)
mapper_fields.button.n.index	`integer`	0 for first button, 1 for second button	Yes (if using buttons)
schedule	`object`	Main configuration object that contains all scheduling settings	Yes
schedule.message_type	`object`	Contains settings about how often and when to send messages	Yes
schedule.campaign_start_date	`object`	Contains settings about when to start the campaign	Yes
schedule.sunset	`object`	Contains settings about when to end the campaign	Yes when message_type.type = 3
schedule.message_type.type	`integer`	Choose how often to send messages: 1 = send once 2 = send on specific dates 3 = send repeatedly	Yes
schedule.message_type.date (for one-time sending)	`integer`	The exact date and time to send the message, in UTC timestamp format. Only used when type = 1	Yes when type = 1
schedule.message_type.date (for multiple dates)	`integer`	List of dates and times to send the message, each in UTC timestamp format. Only used when type = 2	Yes when type = 2
schedule.message_type.interval (for recurring¹ messages)	`integer`	How many seconds to wait between each message send. Only used when type = 3. Cannot be used with days_of_week or days_of_month	Yes when type = 3 and not using days
schedule.message_type.days_of_week (for recurring messages)	`integer`	Which day of the week to send (1-7). Only used when type = 3. Cannot be used with interval or days_of_month	Yes when type = 3 and not using interval or month
schedule.message_type.days_of_month (for recurring messages)	`integer`	Which day of the month to send (1-31). Only used when type = 3. Cannot be used with interval or days_of_week	Yes when type = 3 and not using interval or week
schedule.campaign_start_date.type⁷	`integer`	Choose when to start the campaign: 1 = send immediately 2 = intelligent delivery (The notification will be sent based on user's timezone between 10am to 7pm and on the weekdays of Tuesday, Wednesday and Thursday.) 3 = time (After a fixed time is set, the next one can only be scheduled after 900 seconds.) Please refer to important notes below.	Yes
schedule.campaign_start_date.send_immediately	`boolean`	Must be set to true if starting right away. Only used when type = 1	Yes when type = 1
schedule.campaign_start_date.intelligent_delivery	`boolean`	Must be set to true if letting system choose time. Only used when type = 2	Yes when type = 2
schedule.campaign_start_date.time	`integer`	The specific time to start (in seconds). Only used when type = 3	Yes when type = 3
schedule.sunset.type (for recurring³ campaigns)	`integer`	Choose when to stop the campaign: 1 = Stop on specific date 2 = Never end campaign 3 = Stop after sending X times Only needed for recurring campaigns (message_type.type = 3)	Yes when using recurring messages
schedule.sunset.date (for specific end date)	`integer`	The date to stop the campaign, in UTC timestamp format. Only used when sunset.type = 1	Yes when sunset.type = 1
schedule.sunset.never_end_campaign (for endless campaigns)	`boolean`	Must be set to true for never-ending campaigns. Only used when sunset.type = 2	Yes when sunset.type = 2
schedule.sunset.number_of_send (for limited sends)	`integer`	How many times to send before stopping. Must be a positive number. Only used when sunset.type = 3	Yes when sunset.type = 3

Important Notes:

All timestamps must be UTC.
Include country code in phone numbers (e.g., "91" for India).
Choose only one option for recurring messages: interval, days_of_week, or days_of_month.
Template variables start from .
Maximum 2 buttons per template.
Only one header variable allowed.
Time Interval Requirements

All schedules must be divisible by 900 seconds (15-minute intervals)
Schedules must align with fixed times: HH:00, HH:15, HH:30, HH:45
No arbitrary times between intervals are allowed. Examples:
✅ Valid: 09:00, 09:15, 09:30, 09:45, 10:00
❌ Invalid: 09:05, 09:20, 09:40, 09:50
Non-compliant schedules will be automatically rejected by the system.

1 : In a template, mapper_fields are optional; thus, you can leverage varibles for hyper-personalisation only if the mapper_fields are selected.

2 : Each dynamic field within the body, header, and button is represented by a variable, numbered sequentially as , , and so on.

3 : All mapper fields including, body, header, button, type, value, sub_type, and index will be required only if the variable for each is present in the template.

4 : If media type is document then provide filename as shown in the example.


curl--location 'https://api.advantus.io/api/notifications/whatsapp'\
    --header 'Authorization: YOUR_TOKEN_HERE'\
    --header 'Content-Type: application/json'\
    --data '{
  "campaign_name": "NAME_OF_CAMPAIGN",
  "message_type": "template",
  "template_name": "NAME_OF_TEMPLATE",
  "template_language": "en_US",
  "segment_uuid": "YOUR_SEGMENT_UUID HERE",
  "receiver": [
    "A_VALID_PHONE_NUMBER_WITH_ISO_COUNTRY_CODE"
  ],
  "mapper_fields": {
    "header": {
      "1": {
        "type": 1,
        "sub_type": "document",
        "value": "1618285602295311",
        "filename": "custom_filename.pdf"
      }
    },
    "body": {
      "1": {
        "type": 1,
        "sub_type": "text",
        "value": "09-04-2024"
      },
      "2": {
        "type": 1,
        "sub_type": "text",
        "value": "10-04-2024"
      }
    },
    "button": {
      "1": {
        "type": 1,
        "sub_type": "SHOULD_BE_A_VALID_SUB_TYPE(COUPON_CODE OR/AND URL)",
        "value": "value",
        "index": 0
      }
    }
  },
  "schedule": {
    "message_type": {
      "type": 1,
      "date": 1735516800
    },
    "campaign_start_date": {
      "type": 1,
      "send_immediately": true
    },
    "sunset": {
      "type": 1,
      "date": 1735516800
    }
  }
}
}

WhatsApp message types

There are multiple ways to use WhatsApp messging platform.

Examples

Schema if the header is `text`

"header": {
  "1": {
    "type": 1,
    "sub_type": "text",
    "value": "Hello world"
  }
}

Schema if the media `sub_type` is `image`

"header": {
  "1": {
    "type": 1,
    "sub_type": "image",
    "value": "id or https://unsplash.com/photos/a-person-with-a-surfboard-walking-on-a-beach-WEP4kGnoDhs"
  }
}

Schema if the media `sub_type` is `video`

"header": {
  "1": {
    "type": 1,
    "sub_type": "video",
    "value": "id or https://unsplash.com/photos/a-person-with-a-surfboard-walking-on-a-beach-WEP4kGnoDhs"
  }
}

Schema if the media `sub_type` is `document`

"header": {
  "1": {
    "type": 1,
    "sub_type": "document",
    "value": "id or https://unsplash.com/photos/a-person-with-a-surfboard-walking-on-a-beach-WEP4kGnoDhs",
    "filename": "example.pdf"
  }
}

Schema if the media `sub_type` is `location`

"header": {
    "1": {
        "type": 1,
        "sub_type": "location",
        "location": {
            "longitude": LONG_NUMBER,
            "latitude": LAT_NUMBER,
            "name": LOCATION_NAME,
            "address": LOCATION_ADDRESS
        },
    },
}

Schema if the button `sub_type` is `coupon_code`

"button": {
  "1": {
    "type": 1,
    "sub_type": "coupon_code",
    "value": "code",
    "index": 0
  }
}

Schema if the `sub_type` is `url`

"button": {
  "1": {
    "type": 1,
    "value": "lightbill",
    "index": 1,
    "sub_type": "url"
  }
}

WhatsApp schedule message types

There are multiple ways to use WhatsApp scheduling platform.

Examples

Schema if the message.type either 1, or 2, or 3

{
    "schedule": {
        "message_type": {
            "type": 1,
            "date": 1735516800,
 
            "type":2,
            "date": [1735516800,1735516800],
 
            "type":3,
            "days_of_week": [],
            "days_of_month": [],
            "months_of_year": [],
            "interval":3600
        }
    }
}

Schema if the campaign_start_date.type either 1, or 2, or 3

{
  "schedule": {
     "campaign_start_date": {
        "type":1,
        "send_immediately":true,
 
        "type": 2,
        "intelligent_delivery":"true",
 
        "type": 3,
        "time": 72000
     }
  }
}

Schema if the sunset.type either 1, or 2, or 3

{
  "schedule": {
     "sunset":{
        "type":1,
        "date":1735516800,
 
        "type":2,
        "never_end_camgaign":false,
 
        "type":3,
        "number_of_send":3
     }
  }
}

API response

When making a request, replace value with your token. If the request is successful, you will get a JSON response containing the access token.

Success response use case

If the API receives a successful request, it will typically return specific parameters as part of the response:

Response_payload :

  {
    "success": true,
    "message": "Your notification has been queued for delivery.",
    "data": {
        "notification_id": 10 OR "schedule_id": "5c1f2266-b4fc-4bfe-84ef-819e552cc6da"
    }
}

field	Data type	Description	Required
success	`boolean`	Indicating whether the request was successful or not.	Yes
message	`boolean`/`string`	Informs of additional value if sent along with the response, which can be either false or a string that defines the action done by the API caller.	Yes
data	`object`	A JSON `object` containing information related to the request	Yes
data.notification_id	`integer`	A notification ID generated after making an API call.	Yes
data.schedule_id	`string`	Only received at the time of whatsapp scehduling	Optional

Failure response use case

If the WhatsApp request fails, the API will return specific parameters (HTTP errors) as part of the response:

Error Code	HTTP Status	Cause	Solution
1227	400	invalid template language	Provide a valid available template languages from the available options
1274	400	invalid segment	Provide a valid segment
1339	400	audience missing	Select a correct segment with audience
1341	400	incorrect WhatsApp business id	Provide a valid WhatsApp business id
1342	400	invalid token	Provide a valid WhatsApp token
1343	400	invalid WhatsApp configuration	Configure your WhatsApp setting with Advantus
1345	400	invalid `type`	Provide a valid type (either 0 or 1)
1346	400	invalid mapper fields key	Provide correct key names (body, header, button) in the mapper fields
1347	400	blank/missing template value	Provide a valid template value
1348	400	incorrect index sequence	Provide a valid index sequence (0 and 1)
1349	400	invalid `sub_type`	Provide a valid value for `sub_type` (location, image, video, or document)
1350	400	missing/invalid location	Provide a valid location (longitude, latitude, name, address) Note: Longitude and latitude cannot be a string value.
1358	400	Invalid mobile number format	Ensure mobile number follows the required format
1359	400	Invalid schedule message type	Specify a valid message schedule type
1360	400	Invalid scheduled message date	Provide a valid date for scheduled messages
1361	400	Invalid scheduled advanced settings	Check and correct the advanced scheduling settings
1362	400	Invalid timezone setting for scheduled delivery	Ensure correct timezone is specified for scheduled delivery
1363	400	Invalid campaign start date	Provide a valid start date for the campaign
1364	400	Missing schedule parameters	Provide either 'interval' or at least one of: 'days_of_week', 'days_of_month', or 'months_of_year'
1365	400	Invalid schedule time	Specify a valid time for scheduling
1366	400	Invalid days of week	Provide valid days of the week values
1367	400	Invalid days of month	Provide valid days of the month values
1368	400	Invalid months of year	Provide valid months of the year values
1369	400	Invalid date selection for immediate campaign	Cannot select future date when campaign is set to start immediately
1374	400	Past date selected	Select a future date where required
1375	400	Invalid sunset date	Provide a valid sunset date
1376	400	Invalid sunset type	Specify a valid sunset type
1377	400	Invalid never-end campaign setting	Provide valid settings for never-ending campaigns
1378	400	Missing recipient information	Provide either 'segment_uuid' or 'receiver'
1379	400	Conflicting recipient information	Provide either 'segment_uuid' or 'receiver', not both
1387	400	Invalid schedule payload	Ensure schedule payload is properly formatted
1395	400	Duplicate template name	Choose a unique template name
1396	400	Invalid end date	Ensure end date is after Tuesday

Overview

WhatsApp Messaging with Advantus

Response_payload :