Developers
Conversational App

31min
Introduction to Conversational Apps on WhatsApp
Conversational apps on WhatsApp allow businesses to automate and streamline interactions with their customers, making use of simple text-based communication. Instead of relying on a complex app interface, users initiate conversations by sending any message—whether it’s "Hi", "I need help", or any other input. These messages act as triggers to start the conversational flow.
Peach enables businesses to create and manage these flows using the WhatsApp Flows API. Users can communicate with the business, ask questions, get support, place orders, or handle other interactions entirely within the WhatsApp chat interface. By automating responses, businesses can offer a seamless and efficient user experience, handling everything through natural text conversations.
How Conversational Apps Work
In a WhatsApp conversational app, the interaction starts with a message from the user and proceeds through a series of automated responses, as follows:
User Initiates a Conversation:
The conversation begins when the user sends any message—such as "Hi," "I need help," or any query that initiates communication. This message acts as the trigger for Peach to process the user’s request and begin the conversation flow.
Peach Sends a Request to Your Backend URL:
Once the user’s message is received, Peach sends a request to the backend URL that you’ve configured. This request includes the message from the user, relevant user details, and the context of the conversation. The backend uses this information to decide how to proceed.
Backend Processes the Request:
Your backend processes the incoming request from Peach, identifying the user’s intent based on the message they sent. It may involve querying your internal systems, triggering actions like placing an order, or requesting additional information from the user.
Peach Sends a Response to the User:
After processing, your backend sends a response to Peach, which is then delivered as a message back to the user on WhatsApp. This message could provide the information requested, prompt the user for more details, or present options to continue the conversation.
User Continues the Conversation:
The user responds with additional inputs based on the previous message. Each time the user replies, Peach forwards the message to your backend for further processing, allowing the conversation to evolve based on the user's responses.
Backend Responds with More Information or Prompts:
The backend continues to handle the flow of the conversation by processing each of the user’s replies and sending the appropriate responses. This could involve providing updates, confirming actions, or prompting for further details.
Completing the Conversation:
Once the user's query is resolved—whether it's receiving the needed information, completing a transaction, or resolving a support issue—Peach sends a final message, signaling the end of the interaction. The conversation may close or escalate to a human agent if needed.
Conversational Flowchart
﻿
Setting Up Your Backend
Before you can start handling user conversations, you need to configure a backend URL in Peach. This URL acts as the endpoint where Peach sends all incoming user messages. Every message sent by users—regardless of content—will trigger a request from Peach to this backend URL.
Peach sends these requests in a standard format, which includes details such as the user’s message, ID, and conversation context. Your backend system will process these requests to determine how to continue the conversation and send appropriate responses back to Peach.
Insert Backend URL
﻿
In the next sections, we will explore the payload structure of the requests Peach sends, how to manage them, and how to optimise the conversation flow for your business.
﻿
Peach Request
Peach initiates conversations by sending requests in a specific format to the backend URL you have set up. These requests include vital information such as the user's contact details, the type of conversation being initiated, and any relevant contextual data. Developers are expected to handle these requests and respond appropriately to create a smooth user experience.
Standard Request Format Example:
JSON
{
  "type": "stream.init",
  "request": {
    "id": "se_98234y8h8",
    "contact": {
      "name": "John",
      "phone_number": "+91 98765 43210"
    },
    "params": {},
    "message": {
      "id": 123,
      "text": "Start Stream"
    },
    "context": {}
  }
}
{
  "type": "stream.init",
  "request": {
    "id": "se_98234y8h8",
    "contact": {
      "name": "John",
      "phone_number": "+91 98765 43210"
    },
    "params": {},
    "message": {
      "id": 123,
      "text": "Start Stream"
    },
    "context": {}
  }
}
﻿
Parameters:
type: Indicates the type of event or response. stream.init signifies the initiation of a new conversational stream and stream.in_progress signifies the conversational stream is in progress.
request.id: A unique identifier for the request, used for tracking and correlation.
contact: Contains information about the user, such as their name and phone number. This helps personalise the conversation.
message: Details about the message that triggered the event, including its ID and text content.
context: Additional context or metadata related to the request or conversation. This could include prior interactions or any other relevant data.
This format serves as the standard structure for requests that Peach sends. Developers need to parse this format to extract relevant information and take appropriate actions, such as initiating a conversation, processing user inputs, or managing user states.
﻿
Customising and Handling Peach Payloads
The following sections describe various payload structures that developers can use in response to Peach requests. These payloads allow for customising user interactions, sending messages, handling user preferences, and managing conversations efficiently.
1. Send Welcome Message and Ask Question
The send_message action is used to send a welcoming message to the user, while the send_prompt action is used to ask the user a question and gather input. This combination is typically used at the start of a conversation to initiate engagement.
Payload Example:
Text
{
  "changes": [
    {
      "action": "send_message",
      "message": {
        "text": "Hello, how can I help you?",
        "media_url": "https://example.com/image.jpg"
      }
    },
    {
      "action": "send_prompt",
      "prompt": {
        "key": "name"
      }
    }
  ]
}
{
  "changes": [
    {
      "action": "send_message",
      "message": {
        "text": "Hello, how can I help you?",
        "media_url": "https://example.com/image.jpg"
      }
    },
    {
      "action": "send_prompt",
      "prompt": {
        "key": "name"
      }
    }
  ]
}
﻿
Parameters:
text: The text content of the message. This is the greeting or initial message sent to the user.
media_url: (Optional) URL of an image, video, or other media to accompany the message.
key: A unique identifier for the prompt. This key will be used to capture and reference the user's input later in the conversation.
The above payload sends a message asking how the company can assist, followed by a prompt asking for the user's name. The key is crucial as it allows Peach to store the user's response, which can then be used in subsequent interactions.
﻿
2. Sending Template Message
Template messages are predefined message formats that can include dynamic data fields. They are particularly useful for sending standardised messages like order confirmations, delivery updates, or appointment reminders.
Payload Example:
Text
{
  "changes": [
    {
      "action": "send_template_message",
      "template_message": {
        "system_name": "whats_app_template.system_name",
        "data": {
          "media_url": "https://example.com/image.jpg",
          "tracking_link": "https://example.com/tracking?id=123"
        }
      }
    }
  ]
}
{
  "changes": [
    {
      "action": "send_template_message",
      "template_message": {
        "system_name": "whats_app_template.system_name",
        "data": {
          "media_url": "https://example.com/image.jpg",
          "tracking_link": "https://example.com/tracking?id=123"
        }
      }
    }
  ]
}
﻿
Parameters:
system_name: The unique identifier for the template message within the system.
data: A JSON object containing key-value pairs that populate the dynamic fields within the template. For example, media_url can be used to attach an image or document, while tracking_link can be a URL to track an order.
In this example, a template message is sent with a tracking link and an image. The system_name ensures that the correct template is used, and the data field customises the content of the message for the specific user.
﻿
3. Sending Prompt with Options
The send_prompt action with options allows you to present the user with a set of predefined choices. This is useful for situations where the user needs to select from multiple options, such as selecting a product category, choosing a service, or indicating preferences.
Payload Example:
JSON
{
  "changes": [
    {
      "action": "send_prompt",
      "prompt": {
        "key": "gender",
        "options": [
          {
            "title": "Male",
            "value": "m"
          },
          {
            "title": "Female",
            "value": "f"
          }
        ]
      }
    }
  ]
}
{
  "changes": [
    {
      "action": "send_prompt",
      "prompt": {
        "key": "gender",
        "options": [
          {
            "title": "Male",
            "value": "m"
          },
          {
            "title": "Female",
            "value": "f"
          }
        ]
      }
    }
  ]
}
﻿
Parameters:
key: A unique identifier for the prompt.
options: An array of objects, each representing a selectable option. Each object must include a title (what the user sees) and a value (what is sent back to the system when the option is selected).
In this example, the user is asked to select their gender. The prompt presents two options, "Male" and "Female," and captures the user's selection using the key. This approach standardises user input, ensuring that the system receives consistent and predictable responses.
﻿
4. Sending Prompt with Options Group
This action allows you to present grouped options, where each group contains multiple choices. This is particularly useful when the options are hierarchical or need to be categorised for clarity.
Payload Example:
JSON
{
  "changes": [
    {
      "action": "send_prompt",
      "prompt": {
        "key": "experience",
        "button": "Select Experience",
        "options": [
          {
            "title": "Junior",
            "values": [
              {
                "title": "0-1 years",
                "description": "zero to one years of experience",
                "value": "0-1"
              },
              {
                "title": "1-3 years",
                "description": "one to three years of experience",
                "value": "1-3"
              }
            ]
          },
          {
            "title": "Senior",
            "values": [
              {
                "title": "3-5 years",
                "description": "three to five years of experience",
                "value": "3-5"
              }
            ]
          }
        ]
      }
    }
  ]
}
{
  "changes": [
    {
      "action": "send_prompt",
      "prompt": {
        "key": "experience",
        "button": "Select Experience",
        "options": [
          {
            "title": "Junior",
            "values": [
              {
                "title": "0-1 years",
                "description": "zero to one years of experience",
                "value": "0-1"
              },
              {
                "title": "1-3 years",
                "description": "one to three years of experience",
                "value": "1-3"
              }
            ]
          },
          {
            "title": "Senior",
            "values": [
              {
                "title": "3-5 years",
                "description": "three to five years of experience",
                "value": "3-5"
              }
            ]
          }
        ]
      }
    }
  ]
}
﻿
Parameters:
button: The label for the button the user clicks to make a selection.
options: An array of grouped objects, where each group has a title and an array of values. Each value within a group represents a specific choice.
In this example, the user is asked to select their level of experience, categorised as either "Junior" or "Senior." Each category contains specific experience ranges, making it easier for the user to select the most appropriate option.
﻿
5. Closing the Stream
The close_stream action is used to terminate the current conversational session. This is typically used when the interaction has been successfully completed, or no further actions are required.
Payload Example:
JSON
{
  "changes": [
    {
      "action": "close_stream"
    }
  ]
}
{
  "changes": [
    {
      "action": "close_stream"
    }
  ]
}
﻿
This simple payload closes the session, signalling to Peach that no further interactions are expected. Closing the stream helps in maintaining clean and efficient conversational states within the platform.
﻿
6. Handoff Without Assigning to Agent
This action transfers the conversation to a general queue without assigning it to a specific agent. It allows the conversation to be picked up by any available agent.
Payload Example:
JSON
{
  "changes": [
    {
      "action": "handoff",
      "handoff": {
        "message": {
          "text": "One of our agents will be with you shortly"
        }
      }
    }
  ]
}
{
  "changes": [
    {
      "action": "handoff",
      "handoff": {
        "message": {
          "text": "One of our agents will be with you shortly"
        }
      }
    }
  ]
}
﻿
The handoff action places the user in a general support queue. The accompanying message informs the user that they will be attended to by the next available agent.
﻿
7. Handoff with Assigning to Agent
This action specifically assigns the conversation to a designated agent. It ensures that the conversation is handled by the selected agent, perhaps based on expertise or previous interactions.
Payload Example:
JSON
{
  "changes": [
    {
      "action": "handoff",
      "handoff": {
        "agent_id": 12345,
        "message": {
          "text": "One of our agents will be with you shortly"
        }
      }
    }
  ]
}
{
  "changes": [
    {
      "action": "handoff",
      "handoff": {
        "agent_id": 12345,
        "message": {
          "text": "One of our agents will be with you shortly"
        }
      }
    }
  ]
}
﻿
Parameters:
agent_id: The unique identifier of the agent to whom the conversation is being assigned.
Assigning a conversation to a specific agent ensures continuity and personalised service, which can be critical in customer support scenarios where the agent is familiar with the user's history.
﻿
8. Handoff to Grou
This action transfers the conversation to a specific group of agents. It allows the conversation to be managed by a team that specialises in certain types of inquiries.
Payload Example:
JSON
{
  "changes": [
    {
      "action": "handoff",
      "handoff": {
        "group_id": 123,
        "message": {
          "text": "One of our agents will be with you shortly"
        }
      }
    }
  ]
}
{
  "changes": [
    {
      "action": "handoff",
      "handoff": {
        "group_id": 123,
        "message": {
          "text": "One of our agents will be with you shortly"
        }
      }
    }
  ]
}
﻿
Parameters:
group_id: The unique identifier of the group to which the conversation is being assigned.
Routing conversations to groups allows companies to streamline support by ensuring that inquiries are handled by the most appropriate team, enhancing efficiency and user satisfaction.
﻿
9. Opt Out User
The opt_out action is used to unsubscribe a user from receiving further communications. This is often employed in scenarios where a user explicitly requests to stop receiving messages or after they have successfully unsubscribed.
Payload Example:
JSON
{
  "changes": [
    {
      "action": "send_message",
      "message": {
        "text": "You have been successfully unsubscribed"
      }
    },
    {
      "action": "opt_out"
    }
  ]
}
{
  "changes": [
    {
      "action": "send_message",
      "message": {
        "text": "You have been successfully unsubscribed"
      }
    },
    {
      "action": "opt_out"
    }
  ]
}
﻿
This payload sends a confirmation message to the user, followed by the opt_out action, which removes the user from any active communication lists. It ensures that the user will no longer receive messages unless they opt back in.
﻿
10. Opt In User
The opt_in action re-subscribes a user to receive communications. It is typically used when a user explicitly requests to start receiving messages again.
Payload Example:
JSON
{
  "changes": [
    {
      "action": "opt_in"
    },
    {
      "action": "send_message",
      "message": {
        "text": "You have been successfully subscribed"
      }
    }
  ]
}
{
  "changes": [
    {
      "action": "opt_in"
    },
    {
      "action": "send_message",
      "message": {
        "text": "You have been successfully subscribed"
      }
    }
  ]
}
﻿
The opt_in action re-enables messaging for the user. The accompanying message confirms their subscription status, ensuring clarity and transparency in communication.
﻿
11. Add to List
The list action with the add operation adds a user to a specific list. This is useful for segmentation and targeted messaging, allowing businesses to group users based on specific criteria.
Payload Example:
JSON
{
  "changes": [
    {
      "action": "list",
      "list": {
        "id": "lst_12981jdfjoasd9u",
        "operation": "add"
      }
    }
  ]
}
{
  "changes": [
    {
      "action": "list",
      "list": {
        "id": "lst_12981jdfjoasd9u",
        "operation": "add"
      }
    }
  ]
}
﻿
Parameters:
id: The unique identifier of the list to which the user is being added.
operation: Specifies the operation to be performed, in this case, add.
This payload adds the user to a specified list, enabling businesses to target them with specific communications in the future. It’s a key component in managing user groups and personalised marketing efforts.
﻿
12. Remove from List
The list action with the remove operation removes a user from a specified list. This is useful for managing list memberships and ensuring that users no longer receive targeted communications from that list.
Payload Example:
JSON
{
  "changes": [
    {
      "action": "list",
      "list": {
        "id": "lst_12981jdfjoasd9u",
        "operation": "remove"
      }
    }
  ]
}
{
  "changes": [
    {
      "action": "list",
      "list": {
        "id": "lst_12981jdfjoasd9u",
        "operation": "remove"
      }
    }
  ]
}
﻿
This payload removes the user from the specified list, ensuring that they are excluded from future communications associated with that list. It’s crucial for maintaining accurate and up-to-date user segments.
﻿
﻿
Updated 07 Oct 2024
Did this page help you?
Low Code UI App
Messaging API