Chat flow concepts and basics

Event triggers are powerful tools that allow you to initiate specific actions based on how users interact with your chat widget. Think of them as the starting points for your automated workflows, enabling a more personalised and responsive user experience.

However, it's important to note that not all integrations support every type of event trigger. For example, widget-related events like "Chat window opened" or "Before start new thread" might not be supported by some applications due to their reliance on chat widget behaviors.

Supported Event Triggers and Their Use Cases

1. First Visit

   • Description: Activates when a customer visits your website for the first time.
   • Use Case: Greet new visitors with a friendly welcome message and offer assistance, helping to create a positive first impression and guide them through your site.

2. Second Visit

   • Description: Activates when a customer has visited your website previously.
   • Use Case: Acknowledge returning visitors with a personalised message, perhaps highlighting new features or updates since their last visit, enhancing their ongoing engagement.

3. Chat Window Opened

   • Description: Activates when a customer opens the chat window on your widget.
   • Use Case: Display a promotional offer or helpful tips as soon as the chat window is opened, providing immediate value and encouraging interaction.

4. Chat Window Closed

   • Description: Activates when a customer closes the chat window on your widget.
   • Use Case: Trigger a follow-up email or survey to gather feedback on why the chat was closed, helping you understand and improve user experience.

5. Bot Menu Opened

   • Description: Activates when a customer opens the bot menu on your widget.
   • Use Case: Offer additional resources or navigate users to specific sections of your website based on their selections, streamlining their journey.

6. Before Start New Thread

   • Description: Activates when a thread has not yet started or the current thread has ended.
   • Use Case: Prompt users with a question or suggestion to initiate a new conversation, keeping the interaction flowing smoothly.

7. New Thread Started

   • Description: Activates when a customer starts a new thread by sending the first message or command to the chat.
   • Use Case: Automatically provide relevant information or resources related to the user’s initial query, ensuring they receive immediate assistance.

8. New Message

   • Description: Activates with each new message.
   • Use Case: Respond in real-time to user inquiries, offering support or information based on the content of their messages, enhancing responsiveness.

9. Custom Event

   • Description: Can be activated via JavaScript code.
   • Use Case: Tailor specific actions based on unique user interactions or milestones on your website, such as reaching a particular page or completing a form.

10. Chatflow Connected

    • Description: Activates when an agent connects a live chat to a chat flow or when leaving a live chat.
    • Use Case: Notify the system to transfer the conversation seamlessly between automated bots and human agents, ensuring continuity in user support.

11. Chatflow Disconnected

    • Description: Activates when an agent disconnects a chat flow and takes over the conversation.
    • Use Case: Update the user interface to reflect the transition from automated to human support, providing a clear indication that their query is being handled personally.

Additional Options for Each Trigger

• Run Once per Thread: When enabled, the trigger executes only once per conversation thread, preventing repetitive actions within the same interaction.
• Run Only If Thread Is Not Started: This option ensures the trigger activates only if the thread hasn’t begun, meaning no messages have been sent by the visitor yet. It’s useful for initial greetings or introductory messages.

By effectively utilising these event triggers, you can create a dynamic and engaging chat experience that responds intelligently to user behavior. Whether you're welcoming new visitors, assisting returning customers, or ensuring smooth transitions between automated bots and human agents, these triggers help tailor interactions to meet your users' needs seamlessly.

Bot commands are a fundamental feature of the Telegram bot system, and they are also fully compatible with our native live chat widget.

Within the Telegram app, initiating a bot exclusively relies on bot commands. When a user accesses your bot on Telegram, they will encounter a Start button. Clicking this button sends the /start command, which is essential for beginning the interaction. Therefore, when designing a chat flow for Telegram, it is crucial to incorporate the /start command to ensure smooth user initiation.

Similarly, when using bot commands in our live chat widget, they function exactly as they do in the Telegram app. The initial command serves as the entry point for the conversation. When a user opens the chat widget, they will see the Start button. Pressing this button will trigger the /start command, thereby initiating the chat thread.

This consistency between Telegram and the live chat widget ensures that users have a seamless experience regardless of the platform they choose to engage with your bot. By maintaining the use of the /start command across both systems, you provide a unified and user-friendly interaction pathway, facilitating easier access and engagement for all users.

The "Message" action allows you to communicate directly with your customers by sending messages that can contain one or multiple images. Additionally, these messages can include interactive buttons designed to boost engagement.

Within the "Message" action, you have the capability to initiate several supplementary actions:

1. Set Visitor Data: Capture and store crucial information such as the user's email address, name, and phone number for future reference and personalised interactions. (you will need to create the appropriate "variables" in the chat flow builder to store the information you wish to capture)

2. Send Data to URL (Webhook): Seamlessly integrate with other services by transmitting data to specified URLs, facilitating smooth operations across different platforms.

3. Get Data from Google Sheet: This feature allows you to retrieve information from Google Sheets to organise and manage your data effectively. (Please note that this feature is currently under development and not available for use.)

4. Send Data to a Google Sheet: Similar to retrieving data, this function enables you to send and store information in Google Sheets for better data management. (This feature is still in progress and not yet accessible.)

5. Send an Email: Directly dispatch emails to your customers' inboxes, ensuring timely and efficient communication.

6. Send a Telegram Notification: Receive instant notifications through Telegram, keeping you updated on important activities and interactions.

7. Send Push (Mobile App): Receive push notifications via your mobile app. (This feature is currently being developed and is not available yet.)

8. Send Web Push (Browser): Receive push notifications directly to your browser, enhancing real-time communication and engagement.

9. Create a Ticket: Generate support tickets to manage customer inquiries and issues systematically, ensuring efficient resolution.

10. Change the Chat Flow Language: Adapt the conversation to various languages as needed, catering to a diverse customer base.

If you expect a response from the customer, it is crucial to activate the "Wait for Reply" option. This feature ensures that the system pauses to receive and process the customer's input effectively.

Additionally, you can establish validation rules for the input values. For instance, if you require an email address, you can enforce email validation to guarantee that the collected data is accurate and properly formatted.

When you're expecting a response from your customer, start by enabling the "Wait for reply" option within the "Message" action. This ensures your system pauses and waits for the customer's input before proceeding.

Validating Inputs

Next, it's important to validate the information you receive to maintain accuracy. For example, if you're asking for an email address, select "Email" as your validation type. This checks that the input matches the correct email format. If the validation doesn't pass, the system will follow the "Message is invalid" path, prompting the user to correct their input. If everything looks good, the process moves forward through the "Next" port, keeping things smooth and error-free.

Storing User Inputs

Finally, you'll want to save the user's input for future use. To do this, activate the "Save to variable" option found in the Actions section. Then, choose the specific variable where you'd like the input to be stored. This makes it easy to reference the information later, enhancing your ability to provide personalised and responsive service.

By following these steps—waiting for replies, validating inputs, and saving data—you can create a seamless and user-friendly experience for your customers, ensuring interactions are both efficient and effective.

Variables are essential for storing information within your chat flow and enabling conditional logic smoothly.

They come in two types: local and global. Local variables are only accessible within the current thread, meaning they’re confined to that specific conversation. In contrast, global variables can be accessed across all threads for a particular customer, providing consistency and ease of use throughout various interactions.

To create a new variable in the chat flow builder workspace, simply click on the { } icon in the top menu bar. It’s important to remember to enclose your variables in curly brackets { }, ensuring they function correctly.

For example, you might use variables like {email}, {name}, {phone}, {message}, or {website_url}.

Using these variables allows you to personalise and streamline your chat interactions, making them more relevant and engaging for your users. Whether you’re handling inquiries, managing customer information, or automating responses, variables play a crucial role in enhancing the efficiency and effectiveness of your chat flows.

By incorporating variables thoughtfully, you can create a more user-friendly and innovative experience for both tech-savvy and non-tech-savvy individuals across all generations.

This approach not only simplifies complex processes but also aligns with a friendly and approachable brand personality, ensuring your SMB business stands out with clear and informative communication.

Please be aware that forms are exclusively supported on native live chat and are not available on other channels.

If your chat flow incorporates forms, you'll need to implement workaround logic using the "Condition" action. This allows you to run a different flow subtree for platforms that do not support forms.

You can directly send a form to the live chat widget. Additionally, you have the option to disable the main input field for the Form action. This ensures that users cannot send messages until they have submitted the form.

To efficiently manage form data, you can save each field value to a variable. To achieve this, enable the "Save response to variable" option within the Actions section. After enabling, select the desired variable to store the data and enter {fieldID} in the Data field corresponding to each form field.

Condition actions allow you to add smart conditional logic to your chat flows, making interactions more personalised and efficient. For example, you can trigger a specific sub-flow based on a variable’s value, whether an agent is available, or the platform a visitor is using to chat with you.

Each condition action features two pathways for connecting subsequent actions: "true" and "false." The "true" path is followed when the condition is met, while the "false" path runs if the condition isn’t met. This setup enables you to create dynamic responses tailored to different scenarios.

There are several condition types available to suit your needs:

• Variable: Execute actions based on specific variable values, such as user preferences or previous interactions.
• Agent Online: Check if a support agent is available to ensure timely assistance.
• Platform: Adapt your chat flow depending on the visitor’s platform, whether they’re on mobile, desktop, or another device.
• Language: Communicate in the visitor’s preferred language for a more personalised experience.

By utilising these condition types, you can enhance your chat system’s responsiveness and relevance. This not only improves user satisfaction but also streamlines your support processes, making your interactions both innovative and user-centric. Whether your visitors are tech-savvy or not, condition actions help ensure that every chat experience is smooth, effective, and tailored to their needs.

Initiating a new chat flow is straightforward from your current conversation.

Simply select the desired chat flow you wish to begin. Once chosen, identify the specific action that will serve as the entry point for this new flow. This seamless process allows you to transition smoothly without any interruptions.

Whether you're exploring different topics or accessing various features, starting a new flow ensures an organised and efficient experience.

ConverseIQ’s “Start Another Flow” feature allows you to streamline and scale your chatbot conversations by breaking them into smaller, more manageable chatflows. Instead of building one large, complex flow, you can create multiple dedicated chatflows for different use cases or user intents.

By using “Start Another Flow”, you can hand off the conversation to another predefined chatflow when specific conditions are met. This makes your overall setup more modular and easier to maintain.

Benefits of Using Multiple Chatflows:

• Simplified flow design: Keep each flow focused on a specific topic or function.

• Easier maintenance: Update or modify individual flows without affecting the entire conversation.

• Specialised AI assistants: Assign different AI assistants to each chatflow for more relevant responses based on context.

• Greater flexibility: Combine AI-driven and rule-based flows based on your user’s journey or business requirements.

For example, you might have one chatflow for general enquiries, another for lead qualification, and another for support. Based on the user’s responses or behaviour, the chatbot can seamlessly transition between these flows as needed.

This modular approach improves scalability, performance, and the overall user experience of your chatbot.

To get a full understanding on how to set up your GPT AI Assistants, please read the articles on AI Assistant here: AI Assistants

The Keyword Matcher feature enhances your system by using specific keywords to trigger actions, offering a more flexible approach compared to exact condition matching.

To utilize this feature, ensure you have an active OpenAI integration by navigating to the Settings > Integrations page. Without this integration, attempting to use Keyword Matcher will result in an error.

With Keyword Matcher, you can create multiple keyword groups, each tailored to respond to different user inputs. Assign specific actions to each group, and when a user's input includes keywords from a particular group, the corresponding action is automatically executed. This allows for more dynamic and context-aware responses, improving user interactions.

Additionally, Keyword Matcher provides the option to handle scenarios where no keywords are detected in the user input. By linking actions to the "No matched keywords" port, you can define fallback responses, ensuring that your system remains responsive even when unexpected inputs are received.

The feature also includes a special port dedicated to managing errors that may occur during requests to the OpenAI server. This enables you to set up fallback actions, maintaining smooth operation and enhancing reliability.

Overall, Keyword Matcher is a versatile tool that simplifies the process of creating responsive and intelligent interactions.

The "Invite Agent" feature allows customers to transition from an automated chat flow to a human agent seamlessly.

To ensure that the customer's input is effectively passed to the agent dashboard, it is recommended to use the "Message with reply" action before initiating the "Invite Agent" action.

You have the option to specify the department whose agents will receive the chat invitation. This ensures that the customer's query is directed to the appropriate team, enhancing the support experience.

Additionally, a timeout can be set. If no agent connects to the chat within the specified timeframe, predefined actions will be triggered automatically. This prevents customers from being left waiting and ensures continuous engagement.

After the "Invite Agent" step, you can set a subsequent action that will execute once the agent exits the chat. This allows for smooth transitions and proper closure of the chat session, maintaining a professional and user-friendly interaction.

By utilising these settings, you can create a more responsive and efficient support system that caters to both automated and human-assisted interactions. This approach not only improves customer satisfaction but also ensures that your support team can manage inquiries effectively across various departments.

Enhance your chatbot’s accessibility by implementing multilingual capabilities. To add multiple languages, simply incorporate them into your chat flow. The chatbot will automatically select the initial language based on the client’s preferences. For users accessing via a web browser, the language is determined by their browser settings. Meanwhile, for those using Telegram, the language is detected through the Telegram API. If a client’s preferred language isn’t available, the chatbot will default to the primary language.

Important Notices:

1. Manual Language Entry: Currently, when you add multiple languages to your chat flow, you need to manually input all data for each language. This ensures accuracy and consistency across different languages. We’re excited to announce that an auto-translation feature is in the pipeline, which will simplify this process in the near future.

2. Single Language Setup: If you prefer to use a single language other than English, please replace English with your chosen language instead of adding it as an additional option. This approach helps prevent mixed-language elements, such as texts and buttons, ensuring a seamless and user-friendly experience for your audience.

By offering robust multilingual support, we aim to make your chatbot more inclusive and effective for a diverse range of users, supporting your business’s growth and customer engagement.

Our testing tool lets you effortlessly verify your chat flow’s functionality without needing to connect it to the chat widget or any other channel. This means you can ensure everything works smoothly before going live, saving you time and avoiding potential disruptions.

Important Notice: During a test run, the "Invite agent" action will display a limitation notice instead of actually inviting a chat agent. This helps you identify and resolve any issues in your chat flow without engaging live support, ensuring a seamless experience for your business.

Sending a webhook from a chat flow might sound a bit techy, but don’t worry—we’re here to break it down for you. Let’s dive in!

What is a Webhook?

Before we get into the how-to, let’s quickly cover what a webhook actually is.

In plain terms, a webhook is a way for an app to send real-time data to other applications. Think of it as a messenger that delivers information instantly from one place to another.

When you send a webhook from a chat flow, you’re allowing your chat system to communicate with third-party services, facilitating data collection, processing, and response handling.

You can access the webhook's response using the internal variable {webhook._response}, which includes two objects: status and data.

The status of the request is stored in {webhook._response.status}, allowing you to retrieve the actual request status.

The response data is stored in {webhook._response.data}, and its structure will vary depending on the webhook's response.

Enabling Webhooks in Your Chat Flow

To get started with webhooks in your chat flow, you first need to enable them on a specific action within your flow. Here’s how you can do that:

1. Double-Click the Action: Start by double-clicking on the action within your chat flow where you want to enable the webhook.
2. Navigate to the “Actions” Section: Once you’re in the action settings, head over to the “Actions” section.
3. Activate “Send Data to URL”: Look for the option labelled “Send data to URL” and toggle it on. This will open up the webhook settings for you to configure.

With the webhook enabled, you’re ready to tailor its settings to fit your needs.

Configuring Your Webhook Settings

Now that you have the webhook enabled, let’s explore the key settings you’ll need to configure:

1. Webhook URL

This is the address where your data will be sent. Make sure the URL you enter is publicly accessible so your system can successfully deliver the data. Additionally, the receiving server should return a status code of 200 to confirm that the webhook was received successfully.

Pro Tip: Ensure your webhook URL is secure and reliable to avoid any data transmission issues.

2. Method

Webhooks can use different HTTP methods to send data. Currently, your webhook setup supports both GET and POST requests. Here’s a quick rundown:

• GET: Typically used for requesting data without making any changes.
• POST: Used to send data to the server, often resulting in a change or addition of data.

Choose the method that best fits the action you want to perform.

3. Webhook Data

This is where you define the actual data that will be sent through the webhook. Depending on the complexity of your needs, you have two options:

• Built-In Data Editor: Perfect for straightforward requests, allowing you to create a simple JSON request body easily.

{
  "key": "value",
  "key2": "value 2"
}

• Plain JSON: For more complex requests, you can manually craft your JSON by selecting the “Plain JSON” option and editing the JSON data directly.

Example: Sending a POST request with dynamic data

{
  "action": "submit",
  "name": "John",
  "email": "john@doe.com"
}

In this example, {name} and {email} are placeholders that will be replaced with actual values from your chat flow. Remember to ensure these variables are defined and populated before triggering the webhook.

4. Webhook Headers

Headers are additional pieces of information sent along with your webhook request. They can include things like authorization tokens or content types. For instance, you might include an Authorisation header if your receiving server requires it.

Note: When using the Plain JSON editor, the header Content-type: application/json; charset=UTF-8 is automatically included, so you don’t need to add it manually.

Receiving and Handling Responses

Once your webhook is sent, you’ll want to handle the response effectively. Here’s how you can manage and utilize the responses from your webhook:

You can access the webhook's response using the internal variable {webhook._response}, which includes two objects: status and data.

The status of the request is stored in {webhook._response.status}, allowing you to retrieve the actual request status.

The response data is stored in {webhook._response.data}, and its structure will vary depending on the webhook's response.

Immediate Response Handling

Your chat flow is designed to send the webhook before displaying the message in the chat window. This means you can send the webhook and show its results within the same action.

Example Response:

{
    "responseData": {
        "content": "Hello John",
        "object": {
            "ts": 1738579649
        }
    },
    "cache": true
}

If you want to display the "content" field from the response in your chat, you can do so by accessing the internal variable {webhook._response.data.responseData.content}. This ensures that the message “Hello John” is rendered in the chat window seamlessly.

Important: Make sure that you are rendering the response within the same action that sends the webhook for this to work correctly.

Storing Response Data for Later Use

Sometimes, you might want to use the webhook response in subsequent actions rather than immediately displaying it. In such cases, you can store the response in a variable.

Steps to Store Response:

1. Create a Variable: Define a new variable within your chat flow to hold the response data.

2. Assign the Response: Use the internal variable {webhook._response.data} to store the entire JSON response or specific parts of it.

   {"storedResponse": "{webhook._response.data}"}

3. Utilise the Stored Data: In future actions, you can reference {storedResponse.responseData.content} to retrieve specific information like “Hello John”.

This approach keeps your data organised and easily accessible for various parts of your chat flow.

Handling Errors Gracefully

Even the best systems can encounter hiccups, and webhooks are no exception. Here’s how you can manage webhook errors effectively:

Connecting to a “Request Failed” Subtree

To handle errors during webhook processing, you can connect a subtree to the “Request failed” port. This subtree acts as a contingency plan, ensuring that your users are informed and that alternative actions are taken if something goes wrong.

What You Can Do:

• Notify the User: Send a friendly message to inform the user that there was an issue processing their request.

  Example: “Oops! We hit a snag while processing your request. Please try again later.”

• Execute Alternative Actions: Trigger other workflows or actions that can help resolve the issue or provide support.

Benefits:

• Improved User Experience: Users stay informed and aren’t left wondering why something didn’t work.
• Enhanced Reliability: Your system can adapt to issues without significant disruptions.

Best Practices for Using Webhooks

To make the most out of your webhook integrations, here are some best practices to keep in mind:

1. Keep URLs Secure and Reliable

Ensure that the webhook URLs you use are secure (preferably using HTTPS) and hosted on reliable servers. This minimizes the risk of data breaches and ensures consistent data transmission.

2. Validate Incoming Data

Always validate the data received from webhooks to prevent potential security issues or data corruption. Check that the data matches the expected format and contains all necessary fields.

3. Monitor Webhook Activity

Regularly monitor your webhook activity to ensure everything is functioning smoothly. Set up alerts for failed webhooks or unusual activity patterns to address issues promptly.

4. Document Your Webhook Integrations

Maintain clear documentation for all webhook integrations. This includes details about the URLs used, data formats, and any special headers or authentication methods required.

5. Test Thoroughly

Before deploying your webhooks in a live environment, perform thorough testing to ensure they work as expected. Use testing environments or sandbox servers to simulate real-world scenarios without affecting live data.

Real-World Applications of Webhooks

Understanding the practical uses of webhooks can help you leverage them effectively in your projects. Here are a few examples:

1. Customer Support Automation

Integrate your chat system with a customer support tool using webhooks. When a user submits a support request, a webhook can automatically create a ticket in your support system, streamlining the process and ensuring timely responses.

2. Marketing Campaigns

Webhooks can connect your chat flow to marketing automation platforms. For example, when a user signs up for a newsletter via chat, a webhook can add their details to your mailing list, enabling targeted email campaigns.

3. Data Analytics

Send chat interaction data to your analytics platform through webhooks. This allows you to gather valuable insights into user behavior, preferences, and trends, helping you make informed decisions to improve your services.

Troubleshooting Common Webhook Issues

Even with careful setup, you might encounter some common webhook issues. Here’s how to troubleshoot them:

1. Webhook Not Triggering

• Check URL Accessibility: Ensure the webhook URL is correct and publicly accessible. You can use tools like curl or online services like postman to verify the URL’s availability.
• Verify Action Configuration: Double-check that the webhook is correctly enabled on the desired action within your chat flow.

2. Incorrect Response Format

• Ensure JSON Format: Confirm that your webhook response is in valid JSON format. Invalid formats can lead to failed webhook processing.
• Check Status Codes: Make sure the server returns a 200 status code for successful webhook deliveries. Other status codes might indicate errors.

3. Data Mismatch

• Validate Data Fields: Ensure that the data being sent matches what your receiving application expects. Mismatched fields can cause processing errors.
• Use Variables Correctly: When incorporating variables from your chat flow, verify that they’re correctly defined and populated before the webhook is triggered.

4. Authorisation Failures

• Review Headers: If your webhook requires authentication, make sure the necessary headers (like Authorisation tokens) are correctly included.
• Check Credentials: Ensure that any credentials used for authentication are up-to-date and haven’t expired.

Enhancing Your Webhook Integration

To take your webhook integration to the next level, consider the following enhancements:

1. Dynamic Data Handling

Leverage dynamic variables within your chat flow to send personalised data through webhooks. This can enhance user experience by tailoring responses based on user input or behaviour.

2. Combining Multiple Webhooks

Integrate multiple webhooks to perform various actions simultaneously. For instance, you might send data to both your CRM and analytics platforms, ensuring that all systems are updated in real-time.

3. Using Conditional Logic

Incorporate conditional logic within your chat flow to send webhooks only under certain conditions. This can optimise data transmission and reduce unnecessary webhook triggers.

Conclusion

Sending a webhook from your chat flow is a powerful way to integrate with external applications, enabling data collection, processing, and seamless communication across platforms. By following this guide, you can set up and manage webhooks effectively, ensuring your chat system works harmoniously with other tools and services.

Remember to keep your webhook URLs secure, validate incoming data, and monitor webhook activity to maintain a robust and reliable integration. With these best practices in place, you’ll be well on your way to leveraging webhooks to enhance your chat flow and drive innovation within your business.

Happy integrating!

During a test run, you have the option to enable the debug feature.

This handy tool allows you to monitor variable values and actions in real time, providing valuable insights into your application's behaviour.

By activating the debug mode, you can effortlessly track the flow of your program, identify any issues, and ensure everything is running smoothly.

This proactive approach makes troubleshooting more straightforward and enhances the overall efficiency of your development process.