RELE.AI

# WhatsApp

WhatsApp is a simple and secure instant messaging application. The internal WhatsApp integration provides API access to the selected RELE.AI number (can be found in your organization's settings).

The integration provides AppActions that can be used to interact with your users through the RELE.AI number.

Incoming messages will automatically be matched using the workflow configuration to determine which workflow should be executed.

# Incoming Message Structure

Incoming messages from WhatsApp have a predefined structure, as shown below. You can find additional information about each field in the comments.

{
    "operation_type": "incoming_message",
    "payload": {
        "app_id": "", // the internal application id
        "metadata": {
            "user_id": "", // the user's internal id
            "org_id": "" // the organization's internal id
        }
    },
    "message_data": {
        "message_id": "", // the whatsapp message id
        "from": "", // the number of the user that sent the messages to RELE.AI
        "metadata": {
            "num_media": 0, // amount of media files in a single message
            "source_number": "" // the RELE.AI number that was used by the user
        },
        "contacts": [ // according to a VCF definition
            {
                "addresses": [
                    {
                        "street": "",
                        "city": "",
                        "state": "",
                        "zip": "",
                        "country": "",
                        "country_code": "",
                        "type": ""
                    }
                ],
                "birthday": "",
                "contact_image": "",
                "emails": [
                    {
                        "email": "",
                        "type": ""
                    }
                ],
                "ims": [
                    {
                        "service": "",
                        "user_id": ""
                    }
                ],
                "name": {
                    "first_name": "",
                    "middle_name": "",
                    "last_name": "",
                    "formatted_name": "",
                    "prefix": "",
                    "suffix": ""
                },
                "org": {
                    "company": "",
                    "department": "",
                    "title": ""
                },
                "phones": [
                    {
                        "phone": "",
                        "wa_id": "",
                        "type": ""
                    }
                ],
                "urls": [
                    {
                        "url": "",
                        "type": ""
                    }
                ]
            }
        ],
        "message": {
            "type": "", // the type of the message (media or text)
            "body": "", // the message content
            "content_type": "", // in case of media - the content type (e.g., application/pdf)
            "id": "", // in case of media - the media id
            "filename": "" // in case of media - the file name (N/A in case of pictures)
        }
    }
}

# Send Message

Attribute: send_message

Sending a message over WhatsApp. content object defines the message content.

After sending a message via WhatsApp to the user, there are two possible cases:

  1. Wait for a response from the user - RELE.AI sent the message during the workflow run, and we want to wait for a response from the user.
    For example: I sent a message to the user what his name is, and I want to wait for a reply with his name.
  2. Do not wait for a response from the user - The message is the last message on the workflow run. In this case, we want to stop the run after the message is sent to the user - meaning we do not want to collect a response from the user.
    For example: When the workflow finishes running successfully, We want to send a message to the user that the information has been saved successfully.

To define each of the modes, we will define in the output.operation_type object of send message as follows: For wait for response mode, we'll define:

output:
    operation_type: continue_session

For the do not wait mode, we'll define:

output:
    operation_type: drop_session

NOTE

If the object is not provided in send_message, the default is continue_session

# Full send_message example:

# send_message is a simple operation
# that points to the internal WhatsApp integration
type: Operation

# define the pointers to the
# internal app & app action
selector:
    app: whatsapp
    app_action: send_message

# define the send_message payload
payload:
    # pull the message content from the
    # translations
    content:
        type: get_by_lang
        data: hello_world_message

# output object
# wait for response
output:
    operation_type: continue_session

# identifier key
key: hello_world_send_message

TIP

To read more about the internalization of the content visit the translations page

# Send Location Message

Attribute: send_location_message

WhatsApp Location Message (opens new window) let users see a specific coordinate in a map. To send a location over WhatsApp, use the send_location_message AppAction.

This AppActions requires the payload to contain the following location object (opens new window) attributes:

Name Description
longitude Required.
Longitude of the location.
latitude Required.
Latitude of the location.
name Optional.
Name of the location.
address Optional.
Address of the location. Only displayed if name is present.

For example, the following Operation sends the HQ location of Facebook:

# describe the configuration as type operation
type: Operation

# connect to matching configs
selector:
    workflow:
        - send_location_workflow
    app: whatsapp
    app_action: send_location_message

# drop user session when done
output:
    operation_type: drop_session

# define the location data
payload:
    # required attribute
    longitude:
        type: raw
        data: -122.425332

    # required attribute
    latitude:
        type: raw
        data: 37.758056

    # optional attribute
    name:
        type: raw
        data: Facebook HQ

    # optional attribute
    address:
        type: raw
        data: 1 Hacker Way, Menlo Park, CA 94025

# define the internal key
key: location_message

# Send Contact Message

Attribute: send_contact_message

WhatsApp Contact Message (opens new window) sends a VCF contact to the user. To send a contact over WhatsApp use the send_contact_message AppAction.

This AppAction requires the payload to contain the following contact object (opens new window) attributes:

Name Description
addresses Optional.
Full contact address(es) —see addresses object (opens new window).
birthday Optional.
YYYY-MM-DD formatted string.
emails Optional.
Contact email address(es) —see emails object (opens new window).
name Required.
Full contact name —see name object (opens new window).
org Optional.
Contact organization information —see org object (opens new window).
phones Optional.
Contact phone number(s) —see phone object (opens new window).
urls Optional.
Contact URL(s) —see urls object (opens new window).

WARNING

For the release of August 2021, the following attributes only support raw data: addresses, emails, name, org, phones, and urls. Dynamic data pulling (e.g., redis, request, etc.) will be available in the next release.

For example, the following Operation sends a contact to the user:

# describe the configuration as type operation
type: Operation

# connect to matching configs
selector:
  workflow:
    - send_contact_workflow
  app: whatsapp
  app_action: send_contact_message

# drop user session when done
output:
  operation_type: drop_session

# define the payload to the service
payload:
    addresses:
        type: raw
        data:
        - city : Menlo Park
          country :  United States
          country_code: us
          state: CA
          street: 1 Hacker Way
          type: HOME
          zip: 94025

    birthday:
        type: raw
        data: '2012-08-18'

    emails:
        type: raw
        data:
          - email: test@fb.com
            type: WORK
    name:
        type: raw
        data:
            first_name: John
            formatted_name: John Smith
            last_name: Smith

    org:
        type: raw
        data:
            company : WhatsApp
            department: Design
            title: Manager

    phones:
        type: raw
        data:
          - phone: +1 (940) 555-1234
            type: HOME
    urls:
        type: raw
        data:
          - url: https://www.facebook.com
            type: WORK

# define the internal key
key: contact_message

# Send Menu Message

Attribute: send_menu_message

WhatsApp List Messages (opens new window) allow users to choose an option from a pop-up menu. Each menu can contain up to 10 different items. To use the list messages option, use the send_menu_message AppAction.

This AppAction requires the payload to contain the following attributes:

Name Description
header Optional
If you decide to include it, add the desired content to show it on the header of the message.
content Required
Describe the content of the message that the user will see.
footer Optional
Describe the content of the footer that the user will see.
menu_button_text Required
Button content. It cannot be an empty string and must be unique within the message. It does not allow emojis or markdown. RELE.AI will show this text on the button that opens the menu.
Maximum length: 20 characters.
actions Required
A list of items that RELE.AI will show on the menu. Each section contains the title of that second and a list of items that will be shown under it.

WARNING

For the release of August 2021, the following actions attribute only supports raw data. Dynamic data pulling (e.g., redis, request, etc.) will be available in the next release.

For example, the following Operation will show a menu with three sections. Each section will have between 1 and 3 items:

# describe the configuration as type operation
type: Operation

# connect to matching configs
selector:
  workflow:
    - send_menu_workflow
  app: whatsapp
  app_action: send_menu_message

# drop user session when done
output:
  operation_type: drop_session

# define the payload to the service
payload:
  header:
    type: raw
    data: header test from workflow
  content:
    type: raw
    data: content test from workflow
  footer:
    type: raw
    data: footer test from workflow
  menu_button_text:
    type: raw
    data: open list
  actions:
    type: raw
    data:
      - title : section a
        items :
          - title: section a title 1
            description: section a description 1
          - title: section a title 2
            description: section a description 2
          - title: section a title 3
            description: section a description 3
      - title : section b
        items :
          - title: section b title
            description : section b description
      - title : section c
        items :
          - title: section c title
            description: section c description

# define the internal key
key: menu_message

# Send Buttons Message

Attribute: send_buttons_message

WhatsApp Reply Button Message (opens new window) allows the user to choose one option out of three button options. To send a reply button, use the send_buttons_message.

This AppAction requires the payload to contain the following attributes:

Name Description
header_type Optional
For button interactive messages, you can use the following header types: text, video, image, or document.
header Optional
Once you select your type, add the corresponding objects/fields with more information:
For video, image, and document types, use the upload_media action and transfer the media id to the field.
For text type: Add a text field with the desired content.
content Required
Describe the content of the message that the user will see.
footer Optional
Describe the content of the footer that the user will see.
actions Required
You must add at least one button and up to three buttons. Each entry should be a string with the text that will be displayed on the button.

For example, the following Operation uploads a media item to RELE.AI and use it as a header for an interactive message.

# describe the configuration as type operation
type: Operation

# connect to matching configs
selector:
  workflow:
    - send_buttons_image_workflow
  app: whatsapp
  app_action: upload_media

next:
  selector:
    - type: operation
      data:
        workflow: send_buttons_image_workflow
        next: button_message_image_key

# define the payload to the service
payload:
  link:
    type: raw
    data: https://filesamples.com/samples/image/jpeg/sample_640%C3%97426.jpeg
  type:
    type: raw
    data: image/jpeg

# define the internal key
key: upload_image_key

Use the uploaded media as a header for the message:

# describe the configuration as type operation
type: Operation

# connect to matching configs
selector:
  workflow:
    - send_buttons_image_workflow
  app: whatsapp
  app_action: send_buttons_message

# drop user session when done
output:
  operation_type: drop_session

# define the payload to the service
payload:
  header_type:
    type: raw
    data: image
  header:
    data: upload_image_key:id
    type: redis
    rkey_type: hash_map
  content:
    type: raw
    data: content test d
  footer:
    type: raw
    data: footer test f
  actions:
    type: raw
    data:
      - "test"
      - "test1"
# define the internal key
key: button_message_image_key

# Upload Media

Attribute: upload_media

Uploading media objects to RELE.AI allows you to interact with the media files and send them to users during a workflow. To upload a media file to RELE.AI, use the upload_media AppAction.

This AppAction requires the payload to contain the following attributes:

Name Description
link Required
A URL that contains the media file that needs to be uploaded to RELE.AI
type Required
The MIME type of the media file e.g., image/jpeg, application/pdf

For example, the following Operation will upload a given picture from the web to RELE.AI:

# describe the configuration as type operation
type: Operation

# connect to matching configs
selector:
  workflow:
    - send_buttons_image_workflow
  app: whatsapp
  app_action: upload_media

next:
  selector:
    - type: operation
      data:
        workflow: send_buttons_image_workflow
        next: button_message_image_key

# define the payload to the service
payload:
  link:
    type: raw
    data: https://filesamples.com/samples/image/jpeg/sample_640%C3%97426.jpeg
  type:
    type: raw
    data: image/jpeg

# define the internal key
key: upload_image_key

← HubSpot →