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.

field	Data type	Description	Required
campaign_name	`string`	A campaign name is a specific and identifiable name given to a marketing or advertising campaign	No
message_type	`string`	Type of the message that WhatsApp supports such as template, text, location etc. `Supported type : template`	Yes
template_name	`string`	A template name is a specific and identifiable name defined on the WhatsApp business account. You can check the list of available templates in the template section. Only approved WhatsApp templates can be used for sending WhatsApp notification. For more details, please refer to the template section.	Yes, if the `message_type` is template.
template_language	`string`	Should be an ISO-certified language code. The language selected for your template content e.g, en, fr, hi and others supported by WhatsApp.	Yes
segment_uuid	`string`	Either `segment_uuid` or `receiver`. The uuid(Universal Unique Identifier) is a 128-bit value used to identify an entity in system data. It is provided by Advantus to each user present in your segment list. Used when sending WhatsApp messages to a pre-defined audience in the segment.	Yes, if `segment_uuid` is selected.
receiver	`array`	Either `segment_uuid` or `receiver`. An array of numbers of recipients. The receiver is the recipient who will receive the WhatsApp message- a valid phone number with the country code. E.g.,United States: 1, United Kingdom: 44, Australia: 61 etc. Leverage `segment_uuid` for scenarios with multiple recipients.	Yes, if `receiver` is selected.
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³
mapper_fields.body	`object`	There can be n numbers of variables.	Yes
mapper_fields.header	`object`	There can be only one variable.	Yes
mapper_fields.button	`object`	There can be maximum two buttons (call-to-action) in any template.	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
header.text	`string`	Either `text` or `media`. When selecting text, only one veriable can be added.
haeder.media	`string`	Either `text` or `media`. When selecting `media`, can add any of these: Image, video, document⁴, or location.
button.index	`integer`	In the template, the sequence of buttons will be 0 and 1, with 0 positioned as the first button and 1 as the second button.	Yes
button.sub_type.coupon_code	`string`	The coupon code added here gets copied when user taps the button. E.g., FLAT25	Yes
button.sub_type.url	`string`	The user gets redirected to the url added here when taps the button.	Yes

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 null, null, 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.getnotifly.io/api/notifications/whatsapp'\
    --header 'Authorization: YOUR_TOKEN_HERE'\
    --header 'Content-Type: application/json'\
    --data '{
  "campaign_name": "Support Variable",
  "message_type": "template",
  "template_name": "support_variable",
  "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
      }
    }
  }
}'

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
    }
}

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

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.

"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"
  }
}

Overview