Payemoji Dynamic Messaging

Payemoji Dynamic Messaging

Payemoji Conversational & Dynamic Messaging

 Payemoji Dynamic Messaging allows the use of a single API to send many different Notification message (see how to send a Notification Message here) and other message types.   WhatsApp and other channels allow the use of multiple format types to display rich messages, all requiring construction of different API calls.   Payemoji has made this simple through the use of a library of message types which can be called by their corresponding identification number and populated with variables.   The Payemoji platform then uses these variables, and the message type identified to construct and deliver the message. As an evolution, Payemoji have a very rich 2-way dialog API and service, that enables enterprises to have a conversational with a customer & end user. This same service can be used to drive conversational flows in rich messaging apps.

  

Components

The key components in a Notification message (which can be found in the documentation) are:

·         Channel Type – e.g. WhatsApp, SMS etc

·         Recipient – this is via a standard international phone number format (e.g. +44xx, +1yy) or via the internal Customer identifier which is included in each call from the Dialogue Messaging API if these are being used.

·         Channel Group – this identifies your specific channel and will be provided by Payemoji at setup.

·         Templates – this is the numeric identifier of the template and the set for the sandbox environment is shown below for the different types.

·         Context – this is the area for variables to be passed in key value pairs.   The variables to be used using the Dynamic Messaging is shown below with the appropriate template ID.

The focus of this document is the use of Templates and Context.   The goal of Dynamic Messaging is to allow the reuse of the Payemoji API call with dynamic population of the variables and template IDs depending on the situation the application requires. This vastly simplifies the Enterprise / IT development and is designed to integrate into workflow builders where the complexity of conversational channels is abstracted away e.g. Open conversation with Jim at +44 with variable 1, 2, 3 etc.

Note that some variables are for display in the Payemoji unified inbox so human agents can understand the context of the messages.  These are noted below and for display purposes only and will not be seen by the end user. While many enterprises will use their own CRM inbox, the Payemoji unified inbox can still be used for PoCs, audits and debugging purposes.

 

Message Types

WhatsApp in particular has a wide range of different message types which can be sent such as:

  1. Basic text

  1. Text with Quick Reply Buttons (with or without an image provided by enterprise)

    1. List Pickers

    1. WhatsApp Templates (more on this below)

    1. WhatsApp Flows (forms)

    1. Product Catalogue Messages

    1. Location

    1. Contact

    1. Documents, Audio, Video

    Not all of these messages are supported in this sandbox however all can be created.   Similarly, not all the various permutations and combinations of the different supported message types are available but can be on request to support@payemoji.com.   In our roadmap is the further simplification of these dynamic messages to minimize the number of template IDs per message type.  Note that Basic Text messages are not supported in the Sandbox as these can be sent via Dialogue Messaging.

    For the supported message types below there is further description. We are always happy to add more on request for customers, just reach out to our customer support.

    Sending SMS

    Sending an SMS (where enabled) on Payemoji is the same as for other channels with the change to the channel Type to “SMS”.

    When using the Dialogue Messaging API you are able to send free form SMS within the dialogue.

    Important to note is where the template in the Sandbox includes SMS.   Currently the Sandbox has been developed predominantly for testing WhatsApp however the templates below can be used for both WhatsApp and SMS to get an understanding of the method to manage an omnichannel approach.   Only the Channel Type needs to be changed between “WHATSAPP” and “SMS” the Channel Group and variables stay the same in the notification messages.

    Additional variables specific to SMS can be added.  For example a button in WhatsApp may be intuitive for the user however it might be better to have an additional text variable for SMS to say “Please respond with the number below” or equivalent.   Layout changes can also be made specific to SMS on request.

     

    Name


    Variables

    Quick Reply (Two Buttons) with Image


    var_text,  image, qr1, qr2

    Quick Reply (Three Buttons) with Text Header and Footer


    var_text, qr1, qr2, qr3, var_header, var_footer

    Sandbox Supported Message Types

    1.      Text with Quick Reply Buttons

    Quick Reply messages present with up to 3 buttons a user can quickly click and the text within the button is sent back as a message.   Additional buttons can be provided however these are then hidden beyond the first 3 similar to a List Picker shown below.


    These messages can be constructed using the template IDs in the table below.  

    All the variables to be included in the Context section of the API call are mandatory however additional ones can be included and will be ignored.   For some variables (noted below) a space can be used to create a blank instead of completing the variable with text. 

    For those where spaces are allowed different templates can be created without most of these variables.

    Variable

    Description

    “Space Only” Allowed

    var_text

    This is the text which will be displayed in the body of the message.  Maximum 1024 characters

    Yes

    image

    The full URL of an accessible file such as from a cloud hosted blob.  Located in the Header of the message.  PNG and JPEG accepted.  These are best in 16:9 format and kept as small as possible for faster load time.

    No – mandatory

    var_header

    Text for create as a header in the message.  This is bolded and at the top.  Not available if using an image.  Maximum 60 characters

    Yes

    var_footer

    Text for the bottom of the message and is shown as slightly smaller.  Maximum 60 characters

    Yes

    qr1-3

    The Quick Reply Button text.  Maximum of 20 characters

     

    message_desc

    A descriptor of the message for display in the Payemoji Inbox

    Not yet Enabled

     

    Quick Reply Templates in Sandbox

    Name

    Variables

    Quick Reply (One Button) with Image

    var_text,  image, qr1

     

    Quick Reply (One Button) with Text Header and Footer v2

    var_text,  qr1, var_header, var_footer

    Quick Reply (Two Buttons) with Image

    var_text,  image, qr1, qr2

    Quick Reply (Two Buttons) with Text Header and Footer

    var_text,  qr1, qr2, var_header, var_footer

    Quick Reply (Three Buttons) with Image

    var_text,  image, qr1, qr2, qr3

    Quick Reply (Three Buttons) with Text Header and Footer

    var_text, qr1, qr2, qr3, var_header, var_footer

     

     

    2.      List Picker

    List Pickers are extended versions of Quick Reply to select a single item from up to 10 different options using a radio button.  The initial list is hidden from the user. Note if greater than 10 items, then the tenth item can be more and point to another list. This is a WhatsApp restriction for customer experience.


     

    List pickers have the added feature of a sub-line to add more detail to the selection criteria.   All templates below include this but can replaced with a space or additional templates provided without the field included.

    The variables here are similar to those for Quick Reply with a few additions.

    Variable

    Description

    “Space Only” Allowed

    var_text

    This is the text which will be displayed in the body of the message.  Maximum 1024 characters

    Yes

    image

    The full URL of an accessible file such as from a cloud hosted blob.  Located in the Header of the message.  PNG and JPEG accepted.  These are best in 16:9 format and kept as small as possible for faster load time.

    No – mandatory

    var_header

    Text for create as a header in the message.  This is bolded and at the top.  Not available if using an image.  Maximum 60 characters

    Yes

    var_footer

    Text for the bottom of the message and is shown as slightly smaller.  Maximum 60 characters

    Yes

    list_name

    The title be used on the button to expand the list as well as the title when expanded.  Maximum length 20 characters

    No - Mandatory

    list_n

    Where “n” is replaced by the index of the listed item.   This is the main item being selected.  Maximum 24 characters

    Yes (but leaves a radio button)

    sub_list_n

    Where “n” is replaced by the index of the listed item.   This is the description of the item being selected.  Maximum 72 characters

    Yes

     

    List Picker Templates in Sandbox

    Name

    Variables

    List Picker 4 Choices

    var_header,  var_text, var_footer, list_name, list_1, list_1_sub, list_2, list_2_sub, list_3, list_3_sub, list_4, list_4_sub

     

    List Picker 5 Choices

    var_header,  var_text, var_footer, list_name, list_1, list_1_sub, list_2, list_2_sub, list_3, list_3_sub, list_4, list_4_sub, list_5, list_5_sub

    List Picker 6 Choices

    var_header,  var_text, var_footer, list_name, list_1, list_1_sub, list_2, list_2_sub, list_3, list_3_sub, list_4, list_4_sub, list_5, list_5_sub,  list_6, list_6_sub

    List Picker 7 Choices

    var_header,  var_text, var_footer, list_name, list_1, list_1_sub, list_2, list_2_sub, list_3, list_3_sub, list_4, list_4_sub, list_5, list_5_sub,  list_6, list_6_sub, list_7, list_7_sub

    List Picker 8 Choices

    var_header,  var_text, var_footer, list_name, list_1, list_1_sub, list_2, list_2_sub, list_3, list_3_sub, list_4, list_4_sub, list_5, list_5_sub,  list_6, list_6_sub, list_7, list_7_sub, list_8, list_8_sub

     

    3.      WhatsApp Templates

    To avoid WhatsApp becoming a spam filled channel, any “business initiated” message (that is, an outbound message sent by the business to a user who has not sent a message to the business in the previous 24 hours) requires to be approved by WhatsApp.

    These can be created by Payemoji on your behalf or by you if using Dynamic Messaging through the Meta Administration portal.  For any additional WhatsApp Templates required in the Sandbox these will need to be setup by Payemoji as this is attached to the Payemoji Meta account however in production this could be managed by you or your customer.

    Approval by WhatsApp is usually done within minutes and creation of these are quite straightforward for experienced providers like Payemoji.   However, they can only be changed once per day and do limit what is included in the text versus what are in variables.

    In short, if you wish to send a message to a user who has not sent a message to the phone number in the last 24 hours you must use a WhatsApp Template, or the message will not be delivered.

    Variables for a WhatsApp template are similar to those for Quick Reply.   Variables can be included when inside the WhatsApp  Templates however their use is limited.    Note that a variable can also be added to a URL within a button, but that variant is not covered in the Sandbox but can be provided.

     

    Variable

    Description

    “Space Only” Allowed

    var_text

    NOTE:  for WhatsApp templates this variable is NOT sent to the user but included in the inbox only as the text for the Template is already included when sent to WhatsApp.   This field is reserved for use for SMS fallback (if enabled) to determine what to send to the user.

    Yes

    var_template

    The exact name (case sensitive) used within Meta for the name of the WhatsApp template.  The template names in the sandbox are listed below

    No – mandatory

    Image

    The full URL of an accessible file such as from a cloud hosted blob.  Located in the Header of the message.  PNG and JPEG accepted.  These are best in 16:9 format and kept as small as possible for faster load time.

    No – mandatory

    1-4

    These are the variables in the order created in the WhatsApp Template

    Yes

     

    WhatsApp Template Templates in Sandbox

    Name

    Variables

    WhatsApp Template 4 Variables No Image_v2

    var_template, var_text,  1, 2,  3, 4

    WhatsApp Template 3 Variables No Image

    var_template, var_text,  1, 2,  3

    WhatsApp Template 2 Variables No Image

    var_template, var_text,  1, 2

    WhatsApp Template No Variables No Image

    var_template, var_text

    WhatsApp Template 4 Variables With Image

    var_template, var_text, image,  1, 2,  3, 4

    WhatsApp Template 3 Variables With Image

    var_template, var_text, image,  1, 2,  3

    WhatsApp Template 2 Variables With Image

    var_template, var_text, image,  1, 2

    WhatsApp Template No Variables With Image

    var_template, var_text, image

     

    WhatsApp Templates Available to Select From in Sandbox

    Name

    Image

    Numbered Variables

    test_promotion_no_variables

    Yes

    None (note var_text, image and var_template still required)

    test_promotion_1_variable

    Yes

    1 – Date

    test_promotion_2_variables

    Yes

    1 –First  Name

    2 – Date

    test_promotion_3_variables

    Yes

    1 – Name

    2 – Town/Suburb

    3 – Date

    test_promotion

    Yes

    1 – Name

    2 – Town/Suburb

    3 – Time

    4 - Date

    test_appointment_no_variables

    No

    None (note var_text and var_template still required)

    test_appointment_1_variable

    No

    1 - Time

    test_appointment_2_varables

    No

    1 - Name

    2 - Time

    test_appointment_3_variables

    No

    1 - Name

    2 – Time

    3 - Date

    test_appointment_4_variables

    No

    1 - Name

    2 – Time

    3 – Date

    4 - Location

     

     

    4.      WhatsApp Flows (Forms)

    WhatsApp Flows, which are effectively JSON generated forms inside WhatsApp are a powerful addition to the WhatsApp message types.   They allow the collection of information and provides some validation which is complex to build in a free text conversation.  Used for booking, data collection, quotes etc they can be hardcoded in JSON, or the data can be retrieved from an external system written in Node.JS.   In production, creation, editing and management of Flows can be done by Payemoji or through your own Meta Administration interface.  In the Sandbox a single example is available.   Note all Flows must be published in order to be sent.  Other templates are available to send Flows which are not yet published.

    The data collected in the WhatsApp Flow is sent back using the Dialogue Messaging API provided by Payemoji or we can send the data to your designated webhook.


    The variables for a Flow are mostly related to the initial message for the user to instigate the opening of the form.   All the variables for the Flow itself are programmed within the form creation in the Meta portal.

    Variable

    Description

    “Space Only” Allowed

    var_text

    This is the text which will be displayed in the body of the message asking the user to open the Flow (form).  Maximum 1024 characters

    Yes

    formheader

    Text header in the message preceding the form.  This is bolded and at the top.  Not available if using an image.  Maximum 60 characters

    Yes

    formfooter

    Text for the bottom of the message preceding the form and is shown as slightly smaller.  Maximum 60 characters

    Yes

    formid

    The Meta ID of the form

    No - mandatory

    Formscreen

    The initial screen of the Flow to open (case sensitive).   This is usually the name of the first screen in the Flow JSON

    No - mandatory

     

    WhatsApp Flow (Form) Templates

    Name

    Variables

    Send WhatsApp Flow (Form)

    formheader, formfooter, var_text, formid, formscreen

     

     

    Flows are Available within the Sandbox on request.

     

    Sample JSON

    These are all sent via the POST Send Notification method - refer here for further detail


     

     

    Send a Quick Reply Message with 2 Buttons and An Image


    {
        "jsonapi": {
            "version": "1.1"
        },
        "data": {
            "type": "notification-messages",
            "attributes": {
                "channelType": "WHATSAPP",
                "context": {
                    "var_text": "Welcome!   There is lots to see here",
                    "qr1": "AI",
                    "qr2": "Exit"
                }
            },
            "relationships": {
                "recipient": {
                    "data": {
                        "type": "customers",
                        "id": "{{included[].relationships.recipient.data.id}}"
                        //Customer ID from the Dialogue Messaging API
                    }
                },
                "channelGroup": {
                    "data": {
                        "type": "channel-groups",
                        "id": "4"
                    }
                },
                "templates": {
                    "data": [
                        {
                            "type": "templates",
                            "id": "2195"
                        }
                    ]
                }
            }
        }
    }

    Note  the Recipient data type can be changed to “Phones” and an international phone number in the ID to send direct to a phone number.  See Template example below.

     

     Send WhatsApp Template with an Image and 2 Variables


    {
    "jsonapi": {
        "version": "1.1"
    },
    "data": {
        "type": "notification-messages",
        "attributes": {
            "channelType": "WHATSAPP",
            "context": {
                "var_text": "Send template",
                "var_template": "test_promotion_2_variables",
                "1": "Jack",
                "2": "23rd July"
            }
        },
        "relationships": {
            "recipient": {
                "data": {
                    "type": "phones",
                    "id": "+447811111111"
                }
            },
            "channelGroup": {
                "data": {
                    "type": "channel-groups",
                    "id": "76"
                }
            },
            "templates": {
                "data": [
                    {
                        "type": "templates",
                        "id": "2232"
                    }
                ]
            }
        }
    }
    }

     

    Basic Trouble Shooting & Support

    ·         Send an inbound message into the number so that it allows all types of messages to be sent out

    ·         Check you are sending all variables for the templates

    ·         Ensure any image is accessible

    ·         If a WhatsApp Template, ensure that it is Approved

    ·         If a WhatsApp Flow, ensure it is published

    ·         Make sure your number is in the correct format e.g. +12145551212

    You can test any template by using the Payemoji Inbox (https://app.payemoji.com) and setting the user to Agent mode.  If you do have access reach out to support on support@payemoji.com.  The guide for using the Inbox can be found here

    For any issues, please contact your Account Manager or support@payemoji.com

    Our API documentation can be found here.

     

    Complete list of Sandbox Templates

     

    Name

    Variables

    Quick Reply (One Button) with Image

    var_text,  image, qr1

     

    Quick Reply (One Button) with Text Header and Footer v2

    var_text,  qr1, var_header, var_footer

    Quick Reply (Two Buttons) with Image

    var_text,  image, qr1, qr2

    Quick Reply (Two Buttons) with Text Header and Footer

    var_text,  qr1, qr2, var_header, var_footer

    Quick Reply (Three Buttons) with Image

    var_text,  image, qr1, qr2, qr3

    Quick Reply (Three Buttons) with Text Header and Footer

    var_text, qr1, qr2, qr3, var_header, var_footer

    List Picker 4 Choices

    var_header,  var_text, var_footer, list_name, list_1, list_1_sub, list_2, list_2_sub, list_3, list_3_sub, list_4, list_4_sub

     

    List Picker 5 Choices

    var_header,  var_text, var_footer, list_name, list_1, list_1_sub, list_2, list_2_sub, list_3, list_3_sub, list_4, list_4_sub, list_5, list_5_sub

    List Picker 6 Choices

    var_header,  var_text, var_footer, list_name, list_1, list_1_sub, list_2, list_2_sub, list_3, list_3_sub, list_4, list_4_sub, list_5, list_5_sub,  list_6, list_6_sub

    List Picker 7 Choices

    var_header,  var_text, var_footer, list_name, list_1, list_1_sub, list_2, list_2_sub, list_3, list_3_sub, list_4, list_4_sub, list_5, list_5_sub,  list_6, list_6_sub, list_7, list_7_sub

    List Picker 8 Choices

    var_header,  var_text, var_footer, list_name, list_1, list_1_sub, list_2, list_2_sub, list_3, list_3_sub, list_4, list_4_sub, list_5, list_5_sub,  list_6, list_6_sub, list_7, list_7_sub, list_8, list_8_sub

    WhatsApp Template 4 Variables No Image_v2

    var_template, var_text,  1, 2,  3, 4

    WhatsApp Template 3 Variables No Image

    var_template, var_text,  1, 2,  3

    WhatsApp Template 2 Variables No Image

    var_template, var_text,  1, 2

    WhatsApp Template No Variables No Image

    var_template, var_text

    WhatsApp Template 4 Variables With Image

    var_template, var_text, image,  1, 2,  3, 4

    WhatsApp Template 3 Variables With Image

    var_template, var_text, image,  1, 2,  3

    WhatsApp Template 2 Variables With Image

    var_template, var_text, image,  1, 2

    WhatsApp Template No Variables With Image

    var_template, var_text, image

    Send WhatsApp Flow (Form)

    Formheader, formfooter, var_text, formid, formscreen

     

     






      • Related Articles

      • Messaging Service Setup Guide

        Welcome! Our Service delivers a great customer experience right on the customer’s favourite messaging application and allows businesses to go digital in no time at all. Oh and don’t worry if your business calls you away from the sign up your progress ...

      • What is Payemoji? How does it work

        Payemoji is a service of Message My Customer Ltd, a conversational commerce company based in Dublin, Ireland. Payemoji enable businesses to engage with customers, sell products & services, accept digital payments, book appointments, provide any ...

      • How do I approve the Payemoji service in my Meta (Facebook) Business Account?

        For your business’ security, Facebook requires that any service added to your account like WhatsApp is approved by you.   This is very important and great safety measure by Facebook. When your Whatsapp account is ready to go we will send you an email ...

      • How long does it take to setup the service?

        It typically takes around 15-30 minutes of effort to setup the service but it may take a little longer. To save time please review the list of prerequisites documents and information needed to setup the service. After you complete the necessary ...

      • The Complete Guide to Signing Up!

        Welcome! Our Service delivers a great customer experience right on the customer’s favourite messaging application and allows businesses to go digital in no time at all. Oh and don’t worry if your business calls you away from the sign up your progress ...