Conversational App

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 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 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 { "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 { "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 { "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 app message to send an app message, use the following request payload { "changes" \[ { "action" "send app message", "app" { "id" "flw 1234abcd", "whats app template id" "wat 1234abcd", "liquid values" { "foo" "bar" } } } ] } whats app template id is an optional field that will be used if the message is attempted to be sent outside the 24 hour conversation window 4\ 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 { "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 5\ 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 { "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 6\ 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 { "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 7\ 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 { "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 8\ 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 { "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 9\ 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 { "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 10\ 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 { "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 11\ 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 { "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 12\ 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 { "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 13\ 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 { "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