# yellow.ai
> Conversational AI cloud for all
This file contains all documentation content in a single document following the llmstxt.org standard.
## Best practices & effective testing of a Gen AI bot
## Best practices to build a Gen AI bot
You can improve your bot by focusing on **Prompting**, **Designing conversations** and **Model selection**.
### Prompting
- Keep prompts precise and to the point.
- Provide detailed examples to guide the bot (a few short examples are effective).
- Avoid ambiguous or open-ended statements.
- Refrain from repeating the same instructions multiple times.
- Clearly scope the prompt to define its boundaries.
- Include examples of how the output should be formatted.
### Designing conversations
- Focus on one goal per conversation. Use separate goal nodes for multiple goals.
- Limit user inputs to around 5 to avoid confusion.
- Avoid adding too many skills, as this can complicate the goal.
- Provide ample context about the domain and company within the goal.
- Clearly define the bot’s persona.
### Model selection
- Avoid generating facts from the model.
- Set the temperature to a low range (0 - 0.5) for more predictable responses.
- Limit the number of tokens to improve response speed and reduce costs.
- Consider using GPT-4O over GPT-4 for complex use cases due to its lower latency and cost-effectiveness.
-------
## Testing GenAI bots
Follow these steps to test GenAI bots efficiently:
- **Create Test Cases**: Develop at least 100 test cases to cover various scenarios.
- **Conduct Bulk Testing**: Execute bulk tests for these 100 queries to evaluate overall performance.
- **Evaluate Knowledge Base Performance**: Aim for 80% of queries to be answered correctly if the knowledge base is well-implemented.
- **Manually Test Agent/Conversations**: Perform manual testing for conversational agents to ensure nuanced interactions and accuracy.
---
## GenAI bot development lifecycle
## Guidelines to create an effective GenAI bot
1. **Define target audience and major goals**: Understand who your bot is for and what its core objectives are. Categorize these objectives into static or dynamic flows.
2. **Evaluate each flow and select tools**: Analyze each flow's requirements and choose appropriate tools. Start by testing one major flow with different models to establish an MVP, setting the right expectations early.
3. **Prioritize and manage trade-offs**: For cost-sensitive projects, prioritize critical dynamic flows and be ready to simplify or fallback less important flows to static options or Gen AI.
4. **Leverage GPT-3.5 models for dynamic flows**: Where possible, use GPT-3.5 models for dynamic flows to balance performance and budget.
5. **Play to LLM strengths**: Use large language models for tasks that highlight their strengths. Avoid expecting them to perform tasks where they struggle.
6. **Use Knowledgebase (KB) for Q&A**: If your bot includes question-and-answer capabilities, leverage a Knowledge Base for structured, reliable responses.
7. **Evaluate language constraints early**: Assess language limitations and model capabilities upfront to ensure they align with your bot's requirements.
8. **Customer expectations and education**: Setting the right expectations and educating customers on the capabilities and limitations of LLM-based bots is just as important as the technical aspects.
9. **Focus on iteration and testing**: Building the initial Gen AI flow may be fast, but iterating can be time-consuming. Plan for testing and refinement, and consider launching in phases for complex goals.
10. **Compare models before committing**: Test different model versions against your use case before investing too much time. Expect to make adjustments along the way.
## Selecting Gen AI tools
Use the following table to determine the **best Gen AI tool** for your needs:
| **Customer Requirement** | **Suggested Tool/Flow** |
|---------------------------|-------------------------|
| You want to answer from your website & documents without hallucination | KB with in-house LLM |
| You need to answer from your website & documents with a customized persona | KB with GPT |
| You have multi-turn conversations and want dynamic paths on a lower budget | Dynamic flows with GPT-3.5* (comes with tradeoffs) |
| You have multi-turn conversations with a lot of API calling, instructions, and want flawless handling of many cases | Dynamic flows with GPT-4O, 4, 4 turbo |
| You need specific flows with limited input from your end | Static flow |
| You want interactive button-based & different visual elements for a specific channel | Pick a static flow (but be clear on limitations) |
| You want interactive button-based visual elements with a mix of handling flexible conversations | Dynamic flows with GPT-4 variants (Currently quick reply rich media available*) OR keep dynamic flows as fallback to static flows |
| You need to search from a structured database (like products) and answer queries | Product search or Database search + entities to autoskip static flows |
| You want to handle one-level prompt with dynamic validations & replies | Prompt executor |
| You want to leverage the power of LLM for internal workflows (Non-conversational use case) | LLM integration node / custom API |
| You want better intent identification with low training effort | OrchLLM > NLU |
| You want flexibility in handling fallback based on different cases | OrchLLM for more flexibility or design flexible static fallback when limited cases |
| You want a specific agent persona and consistent talking style throughout the bot | OrchLLM persona definition for more flexibility / a mix of custom conversation design vs Gen AI elements (At individual elements, goals can also have persona) |
| You want a multi-lingual bot | Decision based on use case, check KB language list for in-house / For external LLM, check how well LLM works with your language choice |
---
## Common challenges of Gen AI bots
Gen AI/LLMs are powerful tools with their own set of advantages and limitations. When not used correctly, they present challenges.
## LLMs challenges
- **Citing sources**: LLMs often struggle to cite sources accurately, which can lead to fabricated references.
- **Bias**: LLMs may produce biased responses, reflecting prejudiced or stereotypical views.
- **Hallucinations**: LLMs can confidently generate incorrect or misleading information when they cannot answer a question accurately.
- **Mathematics**: LLMs frequently provide incorrect answers to mathematical questions, as they are primarily trained on text data. However, newer models are improving in logical reasoning.
- **Prompt hacking**: Users can exploit prompt hacking techniques to induce inappropriate or undesirable content from LLMs.
------
## Dynamic flow challenges
### Picking the right model by evaluating early
- **GPT-3.5/GPT-3.5 Turbo**: More cost-effective but may exhibit hallucinations, especially with non-specific instructions. They can support 1-2 workflows stably, plus a knowledge base workflow, but may still show some level of hallucination.
- **GPT-4**: Handles 8-10 workflows comfortably and is better for complex cases. Upgrading to newer models when needed can save time and effort.
- **Complex Cases**: GPT-3.5 or older models may struggle with complex scenarios. If issues persist, consider upgrading to a newer model.
- **Dynamic Chat Nodes**: If using GPT-3.5 models, ensure specific points for completion versus continuation. Adding dummy inputs may help manage unexpected exits.
- **Rich Media**: Features like rich media and quick replies are only available for GPT-4. While they can be enabled for lower models, they may not perform as expected.
- **Workflow Combination**: Combine workflows in a sequence as INPUT → WORKFLOW → OUTPUT. For example, if two APIs need to run sequentially without intermediate data, combine them into a single workflow.
:::note
It’s crucial to understand use cases, budgets, and context to select the right model. Higher cost does not always equate to better performance for every use case. GPT-3.5 may not be suitable for complex scenarios with many workflows. You can use different models in different nodes within the same bot, but select GPT-3.5 only for very simple use cases or if cost is a significant constraint.
:::
### Prompt testing and iteration
- **Iterations**: Multiple iterations may be necessary to craft an effective prompt.
- Avoid assuming prompt behavior. Clearly specify what should happen if things deviate from expectations.
- Keep test cases handy for each iteration to ensure thorough testing.
- **Live Performance**: Your prompt might not always perform perfectly in live scenarios.
- Issues may arise if edge cases weren't tested or if there's a mismatch between user expectations and the use case.
- Be prepared to iterate during the initial days of go-live to refine your prompt.
- Gen AI is not infallible but can handle more cases than static flows. Build customer confidence by addressing these issues promptly.
### Dynamic flows may not be the right tool for your bot/flow
Understand where dynamic flows fit best and select your tools wisely.
> For a detailed understanding of dynamic nodes and their suitability, refer to [this documentation](https://docs.yellow.ai/docs/platform_concepts/studio/dynamicchatnode).
-----
## Knowledgebase challenges
- **JavaScript-rendered Content**: Some web pages use JavaScript to render content, which can be challenging for crawlers like Yellow and Google to access. In these cases, integrating with the source data via CMS or customer APIs is recommended.
- **Selective Indexing**: Only index the necessary web pages from a domain to avoid including irrelevant information. For example, search only specific support pages rather than the entire domain.
- **Crawler Restrictions**: Some domains prevent indexing through services like Cloudflare. Customers need to allowlist Yellow’s IP for data ingestion.
- **No OCR Support**: Images and videos cannot be processed for text extraction.
- **Links in Responses**: Generated responses cannot include clickable links, as LLMs may miss critical characters that break the link.
- **Gated Webpages**: Currently, there is no support for indexing gated webpages. Consider using CMS or API approaches instead.
- **Complex Tables**:
- Tables with merged columns/rows and structured relationships between cell values and headers can be difficult to process.
- Excel-like filters may be needed for effective searching.
- Long entity values (e.g., part numbers) are challenging to search due to their similarity with other parts.
- **Duplicate or Conflicting Knowledge**: Duplicate or conflicting information from the same or different sources can result in cluttered search results.
- **Contextual Relationships**: If a topic’s context is in the title while related paragraphs are placed apart, the system may struggle to establish the connection. We are working on improving this at the parser level to enhance performance.
---
## Troubleshooting Gen AI bots
The key to troubleshooting bots is identifying the issue. Once identified, you can either retrain the bot with new input or adjust its existing text and parameters for improvement.
## Navigate to platform logs
1. Open **Automation > Build** and **Preview** the bot.
2. Click the debugger icon to open the console logs.
3. Click **Refresh** to view real-time logs.
4. Review all logs. Click the logs icon to read the log files.
------
## Troubleshooting OrchLLM issues
1. **Verify inputs to the OrchLLM**: Access this log from [OpenAI] Request details.
- Check if the correct user history is passed to the model under messages.
- Verify that model parameters are correct, such as setting a lower temperature for more contained responses.
2. **Verify the response from the model**: Access this log from [Yellow LLM Agent] Model output.
- **Tools**: Identify the model's prediction.
- **Reasoning**: Evaluate why the model chose a particular tool.
- **Response**: Check the final response generated by the model for small talk and general queries.
-----------
## Troubleshooting KB issues
Common Knowledgebase(KB) issues include:
1. A query like “xyz” has information in a file/webpage, but it’s not getting answered.
2. A query like “xyz” was answered previously but is not being answered now, indicating an intermittent error.
3. After publishing, the KB is not working as expected.
4. The sandbox KB response differs from the staging KB response.
For further evaluation, consider the following:
### Identify if it’s a KB issue
1. **Check Conversation Logs**: Look for the KB Response node.
2. **Verify Query Reach**: Visit **Data Explorer > Knowledge Base report** 30-45 seconds after the query. If the query has reached the KB, you should see a row with the query, search results, and response.
### Components to check
You must check the input, the search results generated by the KB, and the final response.
#### Input
- Query
- Conversation history (rephrase query)
- Site key (optional, for Bing search websites)
- Tags (optional, for file tags)
- Search confidence (default is 0.5)
- Model type (optional, with InHouse LLM) source
- Knowledge version
#### Search
- Does the answer exist in the KB index?
- Is the relevant paragraph among the top 20 results for that query (check the KB report)?
- Is the paragraph LLM-friendly (e.g., does it contain table data)?
- What is the position of the knowledge?
- Has the knowledge version changed?
- Are there conflicting or similar results?
#### Response
- The final output from the response model is shown as the answer.
- Depending on use-cases, you can change the background model and prompt it to follow custom rules. Note: This has implications for cost and hallucination.
- Rules cannot be defined here; it’s a prompt that requires iterations.
> Refer to [this document](https://docs.yellow.ai/docs/platform_concepts/studio/kb/confgure-response) for details.
--------
:::info
**Troubleshooting Reference Docs**
1. [How to use KB report](https://docs.yellow.ai/docs/cookbooks/insights/kbdebugging)
2. [How to write KB prompts](https://docs.yellow.ai/docs/platform_concepts/studio/kb/confgure-response)
3. [What is a sitemap.xml](https://www.semrush.com/blog/website-sitemap/)
:::
---
## Handling Gen AI Knowledgebase(KB)
With Gen AI Knowledge Base(KB), inputting a website URL or any data source into the knowledge base automatically creates a customized bot.
> For more information on KB, refer to [this documentation](https://docs.yellow.ai/docs/platform_concepts/studio/kb/overview).
The following table provides you with the insights on when to use KB and when not:
| **When to use KB** | **When not to use KB** |
|--------------------|------------------------|
| To show the information that you feed the feed the bot through links or uploaded docs | For structured/relational data searches like a database or Excel sheet |
| To generate a response from unstructured data | For recommending/promotional use cases |
| To provide instant answers to user queries from the knowledgebase (that is, generate dynamic responses) | If you need very specific keywords used in the answer |
## Data ingestion methods to optimize KB responses
In addition to the quick setup of a [knowledge base](https://docs.yellow.ai/docs/platform_concepts/studio/kb/overview), there are several methods to enhance its performance, improving the tone, complexity, and precision of generated answers:
### Web ingestion
Choose specific subdomains to include or exclude from your domain. You can perform web ingestion using methods such as Sitemap.xml (preferred), in-house crawler, or Bing search engine (add-on).
:::note
- For websites with regularly updated pages, ensure there is a sitemap.xml with mandatory details like [url, lastmod].
- For use cases requiring real-time data (e.g., prices, dates, schedules, event information), avoid web ingestion. Use CMS or custom APIs instead. If the website is managed with a Content Management System (CMS), integrate the KB directly with the CMS.
:::
### Add documents
You can upload documents with a maximum of 25,000 pages per bot (approximately 1,000 files with 25 pages each).
:::note
- OCR support is not available. That is, images and other file or links within the document will not generate any response.
- English and Bahasa languages are benchmarked and supported. Other languages should be tested at scale (200 queries) by pre-sales before committing.
:::
### Ingest data from 3rd party sources
- Zendesk KB
- Confluence pages
- SharePoint folders
- Amazon S3 buckets
- Salesforce KB
- Google Drive
- ServiceNow KB
### Add tags
Tag knowledge optimally to refine searches based on audience. For example, in an Edtech platform, upload documents tagged for students and parents separately. When a parent queries the bot, it pulls from parent-specific documents, while a student’s query retrieves student-focused content. Use tags like *audience:student* and *audience:parent* to filter responses effectively.
---
## Gen-AI OrchLLM
## OrchLLM overview
Orchestrator LLM (Large Language Model) is our in-house, fine-tuned conversational AI model designed to enhance chatbot capabilities by orchestrating multiple goals within a single conversation.
OrchLLM acts as the governing system for deciding which tools to use for each user action, ensuring tailored, holistic conversations. It is particularly useful for improving broken or fragmented conversations.
> For more details, refer to [this documentation](https://docs.yellow.ai/docs/platform_concepts/studio/train/orchllm).
**Benefits of OrchLLM**:
* Enhanced intent identification
* Retains context throughout the conversation window
* Eliminates the need for extensive bot training—just feed simple descriptions
* Enables more human-like, focused small talk
----------
## Writing effective OrchLLM triggers
When adding trigger descriptions, keep the following in mind:
* Your description will be part of a prompt, so ensure it's neither too long nor too short.
* Avoid mentioning example utterances—only include descriptions. Exceptionally, one or two utterances can be added.
* Clearly state when to trigger and when not to trigger.
* You don’t need to include all keywords, but ensure clarity.
* Avoid leaving unused triggers, as this unnecessarily increases prompt length and cost.
**Examples of good and bad triggers**:
---------
## Testing OrchLLM
* Review [conversation logs](https://docs.yellow.ai/docs/platform_concepts/analyze/chat-logs) when the bot gives an unexpected response.
* Check the reasoning in the output log (under content) and adjust the description or prompt as needed.
* If hallucinations occur repeatedly, report them.
**Example**: Open the logs and check the tool or reasoning behind the bot's response. If the output is unexpected, review the tool, reasoning, or response (for small talk) and update the trigger descriptions or fine-tune the bot accordingly.
```
"content": "{\n
\"tools\": [\"compensation change\"],\n
\"reasoning\": \"The user request is about changing the compensation of an employee which aligns with the tool 'compensation change'.\",\n
\"response\": \"\"\n}",
```
****
---------
## Things to consider before building an OrchLLM bot
To build tailored conversations, follow these:
* Define your bot’s persona carefully, specifying what it can and cannot do.
* Move FAQs to the knowledge base—avoid adding large numbers of FAQs directly into the OrchLLM prompt.
* OrchLLM works best with 20-30 triggers or flows.
* When migrating intent-based bots to OrchLLM, summarize intents into concise descriptions.
* If you enable OrchLLM in the sandbox environment, remember it will automatically be pushed to higher environments upon publishing.
--------
## Limitations of OrchLLM V1 (GPT-4o/4/3.5)
- Negation of intents won’t work unless explicitly specified in the prompt (e.g., “I don’t want a demo”).
- Contextual questions like "Why do you need my email?" may not be handled and will trigger fallback responses.
- No disambiguation support.
- Conversation history is cleared upon clicking "home" and automatically after 24 hours.
- Incompatible with mother-child Orch bot architecture.
- Currently available only in English.
- **Nodes where OrchLLM doesn’t work**:
- Input to *store comment* node is not considered for switching.
- *QR button* clicks won’t trigger switching if there's an outward connection from the button.
- *Goal nodes* are excluded from switching.
---
## Gen-AI Advanced level
In this section, you will learn about:
- GenAI bot development lifecycle
- Common challenges faced when using Gen AI bots
- Best practices for building a successful Gen AI bot
- Troubleshooting a Gen AI bot for optimal performance
:::note
To request any feature mentioned in this document, please create a ticket or contact the support team.
:::
---
## Gen-AI (Beginner level)
Generative AI is an artificial intelligence system used to create content such as text, images, audio or code based on input or instructions (prompt) provided by users.
**Examples of Generative AI:**
* **ChatGPT**: A text-based generative AI model that can generate human-like text, answer questions, and write articles or stories based on user prompts.
* **DALL·E**: An AI model that generates images from textual descriptions, allowing users to create visuals by describing what they want to see.
* **MidJourney**: An AI tool that generates artistic images based on text input, producing creative and visually appealing results.
### What is a Model?
A model is a mathematical representation that is trained on data to recognize patterns and make predictions. In Generative AI, content is generated based on the model it has been trained on.
#### How does the Models learn data
For example, imagine teaching a computer to recognize handwritten numbers like "1," "2," and "3." You show it each number and tell it what it is.
The computer starts to notice patterns, like how a "1" is a straight line and a "2" has a curve. With more examples, the computer gets better at recognizing numbers by learning from these patterns.
### Understanding terminologies of GenAI
#### Neural network
A neural network is a basic building block of deep learning. It is a computational model inspired by the structure and functioning of biological neural networks.
For example, if you input the number 9 it is broken down into 784 parts (pixels), which the computer understands as bits and bytes. The model analyzes these pixels to understand and predict the output.
#### Deep Learning
Deep learning uses neural networks with multiple layers to learn complex representations of data.
For example, a neural network trained to recognize the number "9" focuses on identifying that specific pattern, as mentioned in the above example. While a single neural network might be limited to recognizing just one number, deep learning combines multiple layers of neural networks. Each layer learns to identify different numbers, enabling the system to understand more complex patterns and recognize a broad range of numbers, from "1" to "100."
#### Tokens
A token is an individual entity a model can understand. It can be a word, character, part of a word, or even a whole phrase.
For example, the sentence "I don't want to work" can be broken down into tokens like [I, don, 't, want, to, work].
#### Parameters (13B model , 70B model)
The "13B" or "70B" refers to the number of adjustable parameters in the model. Parameters help the model learn the relationship between words, phrases in training data. More parameters mean the model can handle more complex patterns and process larger amount of data.
#### Context
Context is the information or text provided to a model to help it understand and respond to users. It is like giving the model clues about the topic.
For example, if the context is "I love pizza" and the question is "What toppings do you recommend?", the model uses the context to provide relevant topping suggestions.
#### Transformers
Transformers are a type of technology used in language models to understand and generate text. Models like ChatGPT, LLaMA, and Bard are built using this technology.
#### Hallucinations
Hallucinations are when the model makes up information or provides incorrect information.
For example, if user asks "Who invented the telephone?" and the model answers "Albert Einstein," that is a hallucination because the correct answer is Alexander Graham Bell.
#### Prompt
A prompt is the text or question you provide to a language model to start a conversation or get a response.
Example: "Tell me a story about the moon."
#### Pretrained models
Pretrained models are machine learning models that have been trained on large datasets to perform general language understanding tasks, such as text generation or question answering, before being fine-tuned for specific applications.
Example: Bert, GPT, Llama.
#### Fine Tuning
Fine-tuning is the process of taking a pretrained model and refining it with a smaller, domain-specific dataset to adapt it to a particular task or domain. This process improves the model's performance on specific tasks.
Example: The YellowG model, which is fine-tuned specifically for text summarization.
## LLM
LLM (Large Language Model) is a type of Generative AI focused on text-based data. It is trained on large amount of labeled data to predict the next word in a sequence.
Examples: Chat GPT, Bard, Komodo
### Multi-modal LLM
Advanced AI systems that handle and integrate various types of data, such as text, images, audio, video, and context-aware interactions. Input and output are of different modalities:
i. **Multimodal inputs**: Generates multiple types of data, like text and images simultaneously.
ii. **Multimodal outputs**: Generate various types of content, such as producing both text and images from a single input.
### How LLMs are trained?
Large Language Models (LLMs) are trained on vast datasets containing text from books, articles, websites, and so on to understand patterns, grammar, and context in language. During training, the model is fed input sequences and learns to predict the next word in the sequence.
**Sample training data**
* Johnny likes apples
* Sally loves apples
* Johnny and Sally are friends
* Friends share their favorite fruits
* Apples and oranges are both fruits
**Example training sequence**:
Input | Output
------|-------
Johnny | Likes
Johnny likes | apples
Johnny likes apples | EOS (End Of Sentence)
This process is repeated across large amounts of text data to allow the model to learn language patterns.
### How LLMs work?
LLMs predict the next word in a sentence by analyzing patterns and context from the input. The model processes the input step by step, generating an output word or phrase at each stage, based on its understanding of language.
**Example:**
**Input:** What do Sally and John share?
**Output**: Sally and John share apples.
**Examples of tasks LLMs can perform:**
* Writing
> Suggest three names for our analytics platform.
Sure, here are three ideas:
>* NextInsight
>* QuantifyPro
>* Analytics sphere
* Reading
> I love my new llama T-shirt!
The fabric is so soft.
Complaint : No
Department: Apparel
* Chating
>Bot: Welcome to Yellow.ai
User: I would like to learn about AI
Bot: sure, here are some of the resources
User: that's helpful. Thank you.
### Difference between Generative AI and NLP
Generative AI | NLP (Intent) solution
--------------|---------------------
Generates personalized and dynamic responsess | Uses predefined conversation paths
Handles diverse contexts | Ensures zero hallucinations (important in fields like healthcare)
Supports complex language understanding with multiple languages | Low cost
### Sample non-Gen AI conversation flow (Intent-based flow)
In an intent-based flow, the bot follows a predefined sequence of steps without understanding the full context or handling variations in user responses.
For example, if a user asks a question while providing their name and email, the bot may not understand the context and will proceed to the next step in the flow.
To overcome these limitations, you can use Yellow.ai's GenAI features, as they offer better contextual understanding and flexibility.
**Objective**: Build a sample flow that collects user information such as Name and Email. It should display the collected information to the user and handle the FAQ-related queries.
#### Create Non-GenAI flow
To create a non-GenAI flow, follow these steps:
1. Create an intent "Collect user information" to initiate the flow when triggered.
2. Select the start trigger type (Intent) as the "Collect user information".
3. Build the Flow using Nodes to collect the following:
i. Ask for name: "Can you please tell me your name?"
ii. Ask for email: "What is your email address?"
4. Add the FAQs to handle questions related to the user queries such as, "What is the privacy policy for sharing my data?", "How can I update my email information?".
5. Test the flow to ensure the bot can successfully respond to user inputs and complete the flow as intended.
### Challenges with intent based bots
* **Limited contextual understanding**: Intent-based bots struggle to understand contexts beyond predefined intents, leading to inaccurate or irrelevant responses.
**Example**: Can you tell me why you are collecting my details?.
* **Fixed responses and lack of flexibility**: Intent-based bots are confined to static templates, limiting their adaptability to diverse user inputs and scenarios.
**Example**: User provides an email address in a different format.
* **Difficulty in handling ambiguity**: Intent-based bots find it challenging to deal with ambiguous queries, often resulting in confusion or inaccurate responses.
**Example**: User provides both email and name in the same query
* **Scalability and maintenance issues**: Intent-based bots require frequent updates and maintenance to accommodate new intents and variations, leading to scalability and operational challenges.
**Example**: You want to add a new intent and modify the existing intent.
* **Linguistic complexity and multiple language support**: Intent-based bots struggle with complex linguistic structures and supporting multiple languages, hindering their effectiveness in diverse linguistic environments.
**Example**: Expanding the language capabilities of bot to non-English
* **Difficulty in addressing FAQs efficiently**: Intent-based models needs to be trained on all the knowledge sources manually and configure the responses with predefined static responses.
**Example**: Need to upgrade the bot with the company new policy document.
## Yellow.ai GenAI features
1. **[Dynamic chat node](https://docs.yellow.ai/docs/platform_concepts/studio/dynamicchatnode)**: A smart conversational tool that enhances interactions by tailoring responses to user queries, creating a personalized and natural conversational experience.
2. **[Document Cognition - KB search](https://docs.yellow.ai/docs/platform_concepts/studio/kb/overview)**: A system that reads uploaded documents and provides short summaries to help you quickly understand the content.
4. **[Orchestrator LLM](https://docs.yellow.ai/docs/platform_concepts/studio/train/orchllm)**: A dynamic feature that manages conversations and keeps track of context, ensuring smooth and natural interactions.
5. **Agent Loopback** (WIP): A feature that allows the bot to learn from interactions with live agents, enabling it to incorporate new conversational flows and improve its knowledge base through real-world exchanges.
## Generative AI use cases
Following are the some of the use cases of Generative AI:
1. **Text**
i. **Note taking**: Automatically summarizes key points from meetings.
ii. **General writing**: Generates articles, blogs, or reports based on prompts.
iii. **Support** (Chat/Mail): Responds to customer queries through chat or email.
iv. **Sales** (Email): Generates personalized sales emails to engage potential clients.
v. **Marketing** (Content): Creates marketing content for social media posts.
2. **Code**
i. **Code generation**: Automatically writes code based on user input or requirements.
ii. **Code documentation**: Creates documentation for code to explain its functionality and usage.
iii. **Text to SQL**: Translates natural language queries into SQL code for database interactions.
iv. **Web app builders**: Assists in building web applications by generating code and components.
3. **Image**
i. **Image generation**: Creates images from text descriptions or prompts.
ii. **Consumer/Social**: Generates visuals for social media posts and consumer-facing content.
iii. **Media/Advertising**: Generates marketing visuals and ad creatives for campaigns.
iv. **Design**: Assists in designing graphics, logos, and other visual elements.
4. **Speech**
i. **Video synthesis**: Creates videos based on audio or text inputs.
5. **Video**
i. **Video editing**: Automates the editing process by adding effects, transitions.
ii. **Video generation**: Creates videos from text prompts or other inputs.
6. **3D**
i. **3D models**: Generates three-dimensional models from sketches or descriptions.
ii. **3D scenes**: Creates complete 3D environments and scenes for use in games, simulations, or VR
## Challenge/Limitations of GenAI
1. **Knowledge Freeze**
**Challenge**: Large Language Models (LLMs) are trained on a fixed dataset, meaning their knowledge becomes frozen at the time of training and may not reflect real-time information or developments.
**Example**: If an LLM was trained in 2020 and a user asks about a recent news event in 2023, the model may lack accurate information on the topic.
Who has won the premier league 2024?
What is the temperature today in mumbai?
Who is the prime minister of india in 2015?
2. **Input (Output) length limitation**
**Challenge**: LLMs have constraints on the length of input text they can process and the length of output they can generate, which can limit the complexity and depth of conversations.
**Example**: When summarizing a lengthy document, the model may truncate important details due to length limitations, resulting in incomplete or inaccurate summaries.
Input | Output
------|-------
The stock market fluctuated significantly due to unexpected economic news and changes in interest rates. | The Stock market fluctuated due to news.
3. **Hallucinations**
**Challenge**: LLMs may generate responses that are based on real information and "make things up" based on patterns in their training data, which can lead to misinformation.
**Example**: When asked about historical events, the model might invent details or events that never happened, resulting in inaccurate responses.
Input | Output
------|-------
Describe a significant event in the life of Marie Curie | Marie Curie discovered the theory of relativity in 1912, revolutionizing physics
4. **Bias and toxicity**
**Challenge**: LLMs can pick up biases from the training data, leading them to generate harmful or offensive content that continues societal biases and potentially causes harm.
**Example**: If the training data includes gender biases, the model might respond with gender stereotypes, continuing societal prejudices. Similarly, if trained on toxic content, it could produce offensive or harmful responses.
Input | Output
------|-------
What are common career paths for women? | Women are usually teachers or nurses.
5. **Structured data**
**Challenge**: ChatGPT Generative AI faces difficulties with structured data as it focuses on designed text patterns, leading to possible misinterpretation of context, imprecise outputs, and limited training on structured formats.
Country | Population(mil) | Area (Sqkm)
--------|-----------------|----------
Japan | 126.5 | 377,975
India | 1254 | 8,515,767
The population of India is 896 million people
The area of japan is 377,975 sq km
---
## Upgrade to New Engage Module (for app bots)
App bots are now provided with an option to upgrade the Engage module by migrating all the campaign and audience data to the new engage module.
## What's new in Engage - Cloud ?
### User 360
#### *[Know more about User 360](https://docs.yellow.ai/docs/platform_concepts/engagement/cdp/overview)*
### Template manager
### Inbound campaigns
#### *[Know more about Inbound Campaigns](https://docs.yellow.ai/docs/platform_concepts/engagement/inbound/gettingStarted/launchingYourFirstInboundCampaign)*
## What are the limitations?
1. Up to **5 audience table** will be migrated to cloud platform
1. **Segment details will not be migrated**. But you can download all the segment details once the migration is completed
1. **Scheduled campaigns (runs multiple times) will not be resumed**. You need to schedule the campaigns again from cloud UI.
1. **Function executions** using cron jobs will not be supported.
## Who cannot use this feature?
* Bots which has active "**cron jobs**" which runs functions executions will not be able to proceed with the migration process.
* In case of any **in-progress campaigns** you will not be allowed to process with migration. You can try once the in-progress campaigns are completed.
## Step by Step guide for migration process
#### Step 1: Login
Login to https://app.yellowmessenger.com and open your bot
#### Step 2: Open Engagement
Navigate to Engagement module and click on "upgrade to new platform" from top right corner.
#### Step 3: Start Migration
What's new slides will give you a glimpse of new features which will be available in Engage - cloud platform. Click on "start migration" to proceed.
#### Step 4: Wait for Migration progress
Migration window will be opened and the below data will be migrated by default.
1. Preferences details
3. Campaign reports and details
#### Step 5: Proceed User data Migration
* User data migration is optional.
* If you do not want to migrate the older audience table, you can give "skip" and start clean with new cloud module by uploading the user data.
* If you want to migrate the user data to cloud, Click on start
#### Step 6: Select Audience tables to be migarted
You can select up to 5 audience table for migration. Select and give next.
**`Note : Audience tables are sorted in ascending order based on number of rows present in each table.`**
Here, I have selected 5 tables which I would need to migrate to new platform.
#### Step 7: Map your audeince tables properties to new properties
In cloud engage, we maintain single user database called CDP (User 360). Hence we need to merge the audience tables from app to CDP attributes.
[Learn more about CDP (User 360)](https://docs.yellow.ai/docs/platform_concepts/engagement/cdp/overview)
* From left side drop downs you can select you older column names.
* Right side properties are "default CDP properties".
* You can create new property as well and map your existing columns.
* Here, I need to map my older column "number" to "phone number" in new CDP property.
Here, I have *link* and *offer code* as new columns which is not in default CDP properties.
Hence creating, new attribute by clicking on "add new property" and mapping the column.
#### Step 8: Complete User Data Migration
Once the user data migration started, the progress will be shown as below
Once the process is completed you can see this finish screen, where you can download the segment details and open Engage module in new platform.
#### Note:
`You will get this screen only once to download segment details. Post migration as soon as you click on "Engagement" from left vertical tab, you will be redirected to cloud engage.`
## Few benefits of migrating to new cloud engage
1. You can use **User 360 module** which is helps you to unify your user data at single place and maintain rich profile across channels
1. Improvised outbound campaign **overview**.
1. **Whatsapp templates** can be created and submitted directly from yellow's Engage module instead of raising SUD or from facebook business manager.
1. Manage templates across channels (SMS, email, whatsapp, Viber)
1. You can use **inbound campaigns** module
1. You can run **Viber business outbound campaigns**
---
## Universal international freephone number (UIFN)
## UIFN overview
A **Universal International Freephone Number (UIFN)**, also known as a **Universal Toll-Free Number**, allows callers from multiple countries to dial a single number without incurring long-distance charges. UIFN numbers start with **"+800"**, followed by an **8-digit Global Subscriber Number (GSN)**.
### How UIFN works
1. Callers dial their **International Access Code (IAC)**, followed by **"+800"** and the **8-digit GSN**.
2. The call is then routed to the business's designated phone number.
## UIFN pricing and commercials
Below are the charges for purchasing and using a UIFN number with termination on an **India landline PSTN** number connected to the **Yellow platform**.
### General costs
| Charge Type | Cost (INR) |
|------------|-----------|
| **NRC (Non-Recurring Charge) per Number** | 50,000 |
| **Annual Recurring Charge (ARC) per Number** | 50,000 |
For example, if you need **one UIFN number across 17 countries**, you will pay:
- The **NRC and ARC for one UIFN number**
- **Additional per-country charges** (as per the UIFN rate table below)
## UIFN country rate table
:::note
1. **Payphone Origination is Blocked**: Can be enabled at an additional cost.
2. **Mobile Operator Charges**: Some mobile operators may charge the caller an **airtime fee**.
3. **KYC Documentation**: Required as per local regulations.
4. **Pricing Validity**: Prices are valid until **January 31, 2025**.
5. **Latest Pricing**: Contact the **support team** for updates.
:::
> For further assistance, reach out to the **Simple2Call Provisioning Team**.
### Cost breakdown
- **NRC per Number**: One-time charge per country
- **MRC per Number**: Monthly charge per country
- **Fixed & Mobile Origination**: Per-minute rates
| # | Country | Currency | Fixed Origination (INR/min) | Mobile Origination (INR/min) | NRC per Number (INR) | MRC per Number (INR) | Pulse | Delivery Time | Accessibility | Remarks |
|----|-------------|----------|--------------------------|--------------------------|------------------|------------------|-------|--------------|--------------|---------|
| 1 | Argentina | INR | 32.50 | NA | 3,000 | 3,000 | 1 Min | Best efforts | Fixed Only | |
| 2 | Australia | INR | 18.00 | 18.00 | 3,000 | 3,000 | 1 Min | 21 business days | Fixed & Mobile | |
| 3 | Austria | INR | 18.00 | 35.50 | 3,000 | 3,000 | 1 Min | Best efforts | Fixed & Mobile | |
| 4 | Belgium | INR | 11.00 | 44.00 | 3,000 | 3,000 | 1 Min | Best efforts | Fixed & Mobile | |
| 5 | Brazil | INR | 18.00 | 44.00 | 3,000 | 3,000 | 1 Min | Best efforts | Fixed & Mobile | |
| 6 | Bulgaria | INR | 25.00 | 25.00 | 20,000 | 3,000 | 1 Min | Best efforts | Fixed & Mobile | |
| 7 | China | INR | 49.50 | NA | 3,000 | 3,000 | 1 Min | Best efforts | Fixed Only | |
| 8 | Colombia | INR | 23.50 | 23.50 | 3,000 | 3,000 | 1 Min | Best efforts | Fixed & Mobile | No access from Tigo and Uff Movil prepaid |
| 9 | Croatia | INR | 38.50 | 38.50 | 3,000 | 3,000 | 1 Min | Best efforts | Fixed & Mobile | Guaranteed only via Croatian Telecom Fixed Line |
| 10 | Cyprus | INR | 17.00 | 17.00 | 3,000 | 3,000 | 1 Min | Best efforts | Fixed & Mobile | Guaranteed only via Cyta Fixed and Mobile |
| 11 | Czech Republic | INR | 14.00 | 35.50 | 3,000 | 3,000 | 1 Min | Best efforts | Fixed & Mobile | |
| 12 | Denmark | INR | 11.00 | 50.00 | 10,000 | 3,000 | 1 Min | Best efforts | Fixed & Mobile | |
| 13 | Estonia | INR | 12.50 | 75.00 | 4,000 | 4,000 | 1 Min | Best efforts | Fixed & Mobile | |
| 14 | Finland | INR | 31.50 | 31.50 | 12,500 | 6,500 | 1 Min | 21 business days | Fixed & Mobile | |
| 15 | France | INR | 12.50 | 26.50 | 3,000 | 3,000 | 1 Min | Best efforts | Fixed & Mobile | |
| 16 | Germany | INR | 10.00 | 30.00 | 3,000 | 3,000 | 1 Min | Best efforts | Fixed & Mobile | Company name & address required |
| 17 | Greece | INR | 12.50 | 47.00 | 3,000 | 3,000 | 1 Min | Best efforts | Fixed & Mobile | |
| 18 | Hong Kong | INR | 10.00 | 10.00 | 4,000 | 3,000 | 1 Min | Best efforts | Fixed & Mobile | Mobile operator may charge airtime |
| 19 | Hungary | INR | 13.50 | 35.50 | 3,000 | 3,000 | 1 Min | Best efforts | Fixed & Mobile | |
| 20 | Ireland | INR | 18.00 | 77.50 | 3,000 | 3,000 | 1 Min | Best efforts | Fixed & Mobile | |
| 20 | IRELAND | INR | 18.0000 | 77.5000 | 3,000.00 | 3,000.00 | 1 Min | Best efforts | Fixed & Mobile| |
| 21 | ISRAEL | INR | 18.0000 | 18.0000 | 3,000.00 | 3,000.00 | 1 Min | Best efforts | Fixed & Mobile| |
| 22 | ITALY | INR | 50.0000 | 50.0000 | 3,000.00 | 3,000.00 | 1 Min | Best efforts | Fixed & Mobile| |
| 23 | LATVIA | INR | 32.5080 | NA | 3,000.00 | 3,000.00 | 1 Min | Best efforts | Fixed Only | |
| 24 | LUXEMBOURG | INR | 10.0000 | 13.5000 | 4,000.00 | 3,000.00 | 1 Min | Best efforts | Fixed & Mobile| 80% of fixed lines can dial UIFN |
| 25 | MAYOTTE | INR | 32.5000 | 32.5000 | 3,000.00 | 3,000.00 | 1 Min | Best efforts | Fixed & Mobile| |
| 26 | NETHERLANDS | INR | 12.5000 | 50.0000 | 4,000.00 | 3,000.00 | 1 Minute| Best efforts | Fixed & Mobile | Sometimes minor operators decide to block access. |
| 27 | NEW ZEALAND | INR | 11.0000 | 48.0000 | 3,000.00 | 3,000.00 | 1 Minute| Best efforts | Fixed & Mobile | The company-name & address (worldwide) needs to be available. The mobile operator may charge the end user an airtime charge for mobile calls. |
| 28 | PHILIPPINES | INR | 52.5000 | NA | 4,000.00 | 3,000.00 | 1 Minute| Best efforts | Fixed Only | Only access from PLDT network is guaranteed. |
| 29 | POLAND | INR | 15.0000 | 15.0000 | 3,000.00 | 3,000.00 | 1 Minute| Best efforts | Fixed & Mobile | |
| 30 | PORTUGAL | INR | 18.5000 | 55.0000 | 3,000.00 | 3,000.00 | 1 Minute| Best efforts | Fixed & Mobile | |
| 31 | ROMANIA | INR | 20.0000 | 26.5000 | 3,000.00 | 3,000.00 | 1 Minute| Best efforts | Fixed & Mobile | |
| 32 | SINGAPORE | INR | 10.5000 | 10.5000 | 3,000.00 | 3,000.00 | 1 Minute| Best efforts | Fixed & Mobile | Only Fixed callers of other carriers who have pre-registered with SingTel for 001 access are able to call SingTel UIFN by dialing 001 800 XXXX XXXX. Mobile callers from Starthub & M1 networks must be pre-registered with Singtel for 001 service to access this solution. The mobile operator may charge the end user an airtime charge for mobile calls. |
| 33 | SLOVAKIA | INR | 15.0000 | 48.5000 | 4,000.00 | 3,000.00 | 1 Minute| Best efforts | Fixed & Mobile | |
| 34 | SOUTH AFRICA | INR | 37.0000 | 37.0000 | 10,000.00 | 3,000.00 | 1 Minute| Best efforts | Fixed & Mobile | |
| 35 | SOUTH KOREA | INR | 18.0000 | 18.0000 | 3,000.00 | 3,000.00 | 1 Minute| Best efforts | Fixed & Mobile | |
| 36 | SPAIN | INR | 22.5000 | 50.0000 | 3,000.00 | 3,000.00 | 1 Minute| Best efforts | Fixed & Mobile | |
| 37 | SWEDEN | INR | 10.0000 | 29.5000 | 3,000.00 | 3,000.00 | 1 Minute| Best efforts | Fixed & Mobile | |
| 38 | SWITZERLAND | INR | 10.0000 | 48.0000 | 3,000.00 | 3,000.00 | 1 Minute| Best efforts | Fixed & Mobile | |
| 39 | TURKEY | INR | 21.5000 | 21.5000 | 75,000.00 | 3,000.00 | 1 Minute| Best efforts | Fixed & Mobile | |
| 40 | UK | INR | 10.5000 | 10.5000 | 3,000.00 | 3,000.00 | 1 Minute| Best efforts | Fixed & Mobile | The mobile operator may charge the end user an airtime charge for mobile calls. |
---
## Troubleshooting Voice agents
Ensure the proper functioning of voice bots by identifying and resolving common issues such as connectivity problems, voice recognition errors, and response issues.
:::note
**Prerequisites**
* Familiarity with voice bot tables and logs (e.g., callbackstatus_details, call_details_report, api_logs, CDR, notifications report).
* Ability to interpret SSML (Speech Synthesis Markup Language) using tools like MS TTS Studio or https://xmlgrid.net/.
* Access to customer API logs.
:::
## Initial Assessment
1. **Reproduce the issue**: Try to recreate the reported issue.
* Document the steps taken to replicate the problem.
* Collect screenshots or recordings if possible.
3. **Analyze affected records**: Review recordings, chat transcripts, and logs.
4. **Check primary bot tables**: Review `callbackstatus_details, call_details_report, api_logs`.
5. **Data Explorer tables**: Check call details reports (CDR), notifications reports, and analytics.
6. **Validate SSML**: Ensure Speech Synthesis Markup Language (SSML) is valid using tools like MS TTS Studio.
7. **Patch or upgrade**: Check for recent updates or patches to the voice bot system.
8. **Debug logs:** Use the customer’s phone number to analyze production logs and API logs.
9. **Node verification**: Ensure prompt/question nodes are not empty (except in Inbound Hangup cases).
10. **Documentation**: Note down affected SIDs and key observations.
---
## Connectivity Issues
### Symptoms
* The bot does not play the welcome prompt.
* API calls fail to reach the server.
### Steps to Troubleshoot
1. Check platform and voice server connectivity.
2. Verify that the client API endpoint is accessible.
3. Review network logs for disconnections or timeouts.
### Solutions
1. Ensure strong connectivity between the voice server and platform.
2. Check for API endpoint changes (e.g., URL or request/response structure).
----
## Voice Recognition Errors
### Symptoms
* The bot misunderstands user input.
* Low accuracy in recognizing voice commands.
### Steps to Troubleshoot
1. Review call recordings in the callbackstatus_details table.
2. Analyze recent voice logs for recognition issues.
3. Ensure correct language settings and codes are in place.
### Solutions
1. Repeat unclear prompts.
2. Update the bot’s training data by refining intents and entities.
------
## Response Issues
### Symptoms
Delayed or no response from the bot.
### Steps to Troubleshoot
1. Check server load and the bot’s attached numbers.
2. Test the response time of the client API.
### Solutions
1. Optimize server performance by adjusting the number of channels.
2. Ask the client to check for API issues using logs from the api_response table.
-------
## Engage Flows – Calls, WA, and SMS Triggers
### Symptoms
Users did not receive a call, WhatsApp, or SMS notification.
### Steps to Troubleshoot
1. Analyze the target Engage flow analytics (use flow ID from the URL: e.g., https://cloud.yellow.ai/bot/botID/engagement/flows/661cbd4c8c383c6621230a41/analytics).
2. Check the Notifications report for issues with CampaignID.
****
### Solutions
1. Check for telephony-level traffic congestion.
2. Raise WA/SMS issues through a support ticket with the engage team.
------
## Error HTTP Codes and Messages
| Error | Description | Solution |
| ----- | ----------- | --- |
| 4xx Client Errors | Request contains bad syntax or cannot be fulfilled | |
| 5xx Server Errors | Server encountered an error and failed to fulfill the request|
| 500 Status Code | Server failure| Verify the Client API/Bot API and confirm that the endpoint is correct. For Bot API issues, provide bot ID, failure duration, and logs to the support team in a ticket. |
--------
## Log Analysis
:::note
Enabling Auto fallback to Enable summarized results in the Conversation settings, or within any node that invokes document search in a voice flow, will result in an error.
:::
1. Access Logs:
- Navigate to **Analysis → Conversational Logs** or access the relevant database for details on `drop_steps` and `dispositions`.
- Use log analysis tools to filter and search for specific log entries based on sender ID or profile ID.
2. Common Log Entries
| Type | Description |
| -------- | -------- |
| **API Call Logs** | - Provide detailed information on API requests and responses stored in the database. - Useful for diagnosing API related issues (e.g., request failures or incorrect responses). |
| **Voice Interaction Logs** | - Track user interactions and bot responses, offering insights into the flow of conversation. - These logs are found in Data Explorer or custom tables such as `callbackstatus_details`.|
3. Steps to Analyze Logs:
- Locate Errors or Patterns: Look for error messages or unusual patterns in the logs, such as failed API calls or timeouts.
- Cross-Reference Logs with Issues: Compare logs with the specific issues reported by the user to identify potential correlations or causes.
---
### Detailed steps to access logs from Analyze module
1. Navigate to **Analysis → Conversational Logs**. Search for the logs using the customer’s phone number.
****
2. In the chat transcript displayed on the left, locate the message where the issue occurred. Click the Logs icon (debugger) next to the relevant message. Review the logs for any error messages indicating problems at that step.
****
3. Check the callbackstatus event data for any instances where `bot_failed = true` or `bot_failover = true`. This helps identify where the bot encountered failures or fallbacks.
****
****
4. Review the function logs at the step where the issue occurred. If a failure is detected, the function log will show error details such as:
```
[
{
"log": {
"data": "{\"tag\":\"Error while executing the function\",\"extraInfo\":{\"message\":\"Cannot read property 'length' of undefined\"}}",
"level": "error"
}
}
]
```
****
This type of error usually points to a specific issue, such as a missing or undefined property, which can guide further troubleshooting.
By following the above steps, you can isolate specific log entries and errors that contribute to the problem, allowing for targeted resolution.
--------
## Frequently Asked Questions (FAQ)
1. What should I do if the bot is not responding?
Place a call and check the bot logs in the analysis tab and review logs for any errors.
2. How can I improve voice recognition accuracy?
Update utterances in the bot's intents and entities regularly.
---
## How to Determine the Region Where Your Bot is Hosted
This guide explains how to find out in which region your bot is hosted on the platform.
> To know the region of a bot, you must have **access** to the **Platform** and **Bot**.
## Steps to identify bot region
### Method 1: Using the configure button
1. Login to the platform and open your bot.
2. Click on the **Configure** button located at the top right corner of the bot's home page. The region where the bot is hosted will be displayed.
### Method 2: Using the Knowledge Base URL
1. Go to **Knowledge Base** of the bot.
2. Click on **Share** and then copy the URL. The region information is embedded in the URL as `region=`.
****
### Method 3: Using Automation Flows
1. Navigate to **Automation > Build > Flows**.
2. Click on Preview.
****
3. In the preview window, click on the redirection arrow which will open a new page. Check the URL in the new page; the region will be indicated as `region=`.
**Sample URL Format** (In this URL, the region is specified after `region=`):
```
https://cloud.yellow.ai/liveBot/x1667286708237?region=4
```
The region codes in the URL correspond to the following locations:
| **Region Code** | **Location** |
|-----------------|----------------|
| r0 | India |
| r1 | MEA |
| r2 | Jakarta |
| r3 | Singapore |
| r4 | USA |
| r5 | Europe |
| r6 | Qatar |
| r7 | Saudi Arabia |
---
## Handling CORS errors for Chat Widget
Websites often add CSP (Content Security Policy) to restrict loading of content from external sites, which leads to CORS (Cross-Origin Resource Sharing) errors. In such cases, the entire chat widget or specific components like fonts or icons may fail to load.
To resolve CORS errors and ensure the seamless functioning of the chat widget, add Yellow’s domain to the CSP headers of the website. The following domains should be included:
`https://*.yellow.ai`
`https://*.yellowmessenger.com`
To whitelist the WSS (WebSocket Secure) protocol, add the following:
`wss://*.app.yellow.ai`
By adding these domains in the CSP headers, you allow the necessary resources to be loaded, will then allow the bot to load on the website.
---
## Difference between Viber and Viber for business
*** | Viber |Viber for business|
---------|--------|-------------
Target audience | Ideal for personal one-on-one interaction with the bot. | Ideal for business users to interact with larger audience.
Setup | Download the app and install on your mobile device. | Contact [Yellow.ai support team](mailto:support@yellow.ai) with your business details for setup |
Interaction | 1-1 messaging | Many-to-one messaging
Verification | No | Need approval from Viber business team.
Supported message types | Free text messaging Voice and video calls Multimedia sharing | Text Image Files
Campaign/Messages | Supports only promotional campaigns | Supports transactional, promotional, and conversational messages
Customer support | Yes | Yes
Live Agent support | Yes | Yes
Auto responses | Yes | Yes
Business Profiles | Personal profiles are used in the regular Viber app. | Businesses can create official business profiles on Viber for Business, providing a professional identity for customer communication.
API and Integrations | Does not support API or integrations designed for business purposes. | Supports APIs and integrations that businesses can use to integrate Viber into their customer communication systems.
Discoverability | Requires QRCode or Share with a friend option for users to discover and connect. | Offers a searchable feature, allowing users to find and connect with businesses more easily
:::note
The information provided is based on general features, and the specifics may vary. It is recommended to check the latest documentation.
:::
---
## App password generation for email tickets
To ensure reliable email delivery from agents to end users, app passwords can be utilized. This process involves generating an app password to improve communication between agents and users when email integration is used.
> Use the same email ID and password that were integrated into the bot.
1. Log in to the email account that is integrated with the bot.
2. Click [here](https://support.google.com/accounts/answer/185833?hl=en) to create the app password- Google Support App Password.
3. Create the app name. After creating the app name, you will receive a 16-character app password.
4. Prepare the password: Remove any spaces between the characters of the app password. Copy the modified password.
5. Paste the app password into the email settings within the bot.
> If the normal password for the email account is changed, a new app password must be generated and updated in the email settings of the bot.
---
## Difference between Web widget and Mobile SDK
*** | Web widget | Mobile SDK |
-------|----------|------
Destination | Hosted on Website | Hosted on Mobile app
Entry point | Supports both floating bot icon and custom entry point | Supports only custom entry point
Hardware permission |The bot will inherit the same permissions as the browser | Need to define mic, location, storage, and other hardware permissions in the SDK
Optimisation | Better optimized for web browsers | Better optimized for mobile screens and keyboards, with native attachment button support.
Push notifications | Supports browser push notifications which require additional setup (service worker) | Supports Firebase push notifications even without the need of device token. Additionally, you can also configure `sendIOSEvent` to redirect users to any other screen within or outside the app
Navigation | Supports floating icon as an entry point | Supports native entry and exit.When you click on the link it will open in default browser, and upon clicking back, users are redirected to the app
Customisation |Supports custom script to override bot’s UI elements | Supports custom loader (while loading chatbot)
Speech-to-text (STT) & Text-to-speech (TTS) | Supports both | Not supported **Note**: STT is not optimised for Mobile but mobile keypads support STT
---
## Configure multiple themes on Web and Mobile SDKs
You have the option to set a default theme and customize various themes for different pages on your website or mobile app. The configuration includes:
* Bot name
* Primary color
* Secondary color
* Bot icon
* Bot description
* Bot click icon
To implement this on the web, pass the following values inside window.ymConfig in the bot script:
```javascript
theme:{
botName:" ", //Text upto 50 characters
botDesc:" ", //Text upto 50 characters
primaryColor:" ", //RGB or HEX value
secondaryColor:" ", //RGB or HEX value
botBubbleBackgroundColor:" ", //RGB or HEX value
botIcon:" ", //CDN link
botClickIcon:" " //CDN link
}
```
For mobile SDK, send the values as mentioned below:
```c
let theme = YMTheme()
theme.botName = " "
theme.botDesc = " "
theme.primaryColor = " "
theme.secondaryColor = " "
theme.botIcon: " "
config.theme = theme
```
---
## Gupshup (WhatsApp) integration
Integrating Gupshup with the Yellow.ai platform allows businesses to connect their WhatsApp channel through Gupshup and enable two-way communication between the bot and WhatsApp users. This integration ensures that the Yellow.ai bot can send and receive messages to and from WhatsApp users using Gupshup's webhook.
---
## What this integration does
- **Incoming messages** — When someone writes to your WhatsApp business number, Gupshup notifies Yellow.ai. Your bot can then run its flows, AI, or agent handoff as usual.
- **Outgoing messages** — When your bot sends a reply, Yellow.ai sends it to Gupshup so it is delivered on WhatsApp. The **User ID** and **Password** you save in Yellow.ai are what allow those sends to work.
**How it works, in order:**
1. A customer sends a WhatsApp message → **Gupshup** receives it.
2. Gupshup calls the **Webhook URL** from Yellow.ai and includes the **Authorization** value Yellow.ai gave you.
3. Yellow.ai matches that request to your **bot** (the URL contains your bot identifier).
4. When your bot replies, Yellow.ai uses your saved **User ID** and **Password** so **Gupshup** can deliver the reply on WhatsApp.
You save **User ID** and **Password** in Yellow.ai; you register the **Webhook URL** and **Authorization** value in Gupshup so steps 2 and 4 above work.
---
## Before you begin (checklist)
Go through this list once before you start:
| You need | Why |
|----------|-----|
| A **Gupshup** account with **WhatsApp** set up for your business number | Gupshup must already be able to send and receive WhatsApp for that number. |
| Your Gupshup **User ID** and **Password** for WhatsApp | These are the same kind of credentials Gupshup provides for API-based messaging. If you are unsure where to find them, use Gupshup’s documentation or your Gupshup account manager. |
| Your Yellow.ai bot is ready and published. | A live, published bot can receive traffic and run your flows when WhatsApp is connected. |
**Gupshup help for webhooks (optional reading):** [Webhooks overview](https://docs.gupshup.io/docs/webhooks-2) · [Set webhook callback URL](https://docs.gupshup.io/docs/set-webhookcallback-url)
---
## Steps to connect Gupshup in Yellow.ai
Follow these steps **in order**:
1. Log in to **Yellow.ai** platform.
2. Open the **bot** that should use this WhatsApp number.
3. In the left navigation, go to **Extensions** → **Channels**, then use the search bar to search for **Gupshup**.
4. Click **Gupshup (WSP)** in the results to open the channel setup page.
5. On the form you will see:
- **Gupshup User ID** — enter the User ID from your Gupshup account (Customer Care / WhatsApp API credentials).
- **Gupshup Password** — enter the matching password from your Gupshup account.
6. Click **Save**.
Keep your **Gupshup Password** private.
### After you save: Webhook URL and Authorization
After the channel saves successfully, the same page shows two values you will use in **Gupshup** when you configure the webhook there. You can copy each value using the **Copy** control next to it:
| What you copy | What it is for |
|---------------|----------------|
| **Webhook URL** | This is the web address Gupshup must call **every time** there is incoming WhatsApp activity for this bot. It will look like a normal `https://` link and will include your bot’s identifier in the path. |
| **Authorization header value** | Gupshup must send this exact value in the **`Authorization`** HTTP header when it calls the Webhook URL. That way Yellow.ai knows the traffic belongs to this bot. |
:::tip
Always use **Copy** from the Yellow.ai screen. Pasting by hand often causes **401** errors (access denied) because of a missing character or a wrong header.
:::
**What Gupshup’s request should look like (conceptually):**
- Method: **POST**
- Address: your copied **Webhook URL**
- Header: **`Authorization`** = the copied value (no extra word like “Bearer” unless Gupshup’s own screen asks for that format—follow what Yellow.ai shows you as the full value to send)
### Edit or disconnect later
- **Edit** — Repeat the steps above and choose **Edit account** when you need a new **User ID** or **Password**.
- **Disconnect** — Removes this Gupshup connection from the bot until you connect again.
---
## Live chat queue handling for chat widget
When all agents are engaged with incoming chat tickets, you can enable the queue position of users in the chat widget. For more information on how to enable the queue position, click [here](https://docs.yellow.ai/docs/platform_concepts/inbox/inbox-settings/workflows/chat-queue#1-configure-chat-queue).
### Enable the queue position of the user in chat widget
To enable the queue position of the user, follow these steps:
1. Navigate to **Inbox** > **Setting** > **Queue handling**.
2. Enable the queue position display on the widget.
3. Enter a custom message to display the queue position and click **Save**.
4. Go to **Channels** > **Chat widget** > **Deploy** > **Experience on a website**.
* The chat widget will now display the queue position for the user.
---
## Multi-file upload in Chat widget
You can enable uploading multiple files in the chat widget using the [File prompt node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-node-overview/file-prompt-node). The supported file formats are documents (doc, docx, pdf,) images (png, jpeg), videos (MP4, MOV). You can also preview the uploaded files.
##### Limitation
* You can upload upto 5 files simultaneously.
---
## Redirect users to Phone App/Email via QRs, Text Message, or Callout Banner
Brands can configure hyperlinks that redirect users to phone apps or email services in various components like Text Messages, Quick Replies (QRs), Cards, and Callout Banners.
To set up these links:
1. For phone numbers, add tel:`+{phone_number}` to the button link. For example, `tel:+919988776655` will initiate a call when the button is clicked.
2. For emails, add `mailto:{email ID}` to the button link. For example, mailto:apps@yellow.ai will open the default email client when the button is clicked.
---
## Resolving message failures in WhatsApp, Facebook, and Instagram channels
This guide provides steps to identify and troubleshoot message failures when using WhatsApp, Facebook, and Instagram channels.
Message failures can occur due to various reasons such as incorrect configuration, network issues, or platform limitations. Understanding the specific cause of message failures helps in timely resolution and maintaining effective communication.
##### Prerequisites
To troubleshoot message failures, ensure you have the following:
* Access to the Yellow.ai platform.
* Permission to view message logs and configuration settings.
* Knowledge of the specific channel (WhatsApp, Facebook, or Instagram) where the failure occurred.
### Steps to resolve message failure
1. Navigate to the bot where the message failure has occurred.
2. Copy the chat transcript of the user’s WhatsApp number for which the message was not delivered.
3. Open the copied chat transcript in a new tab.
4. Open the **Network** tab > right-click on the page > select **Inspect**.
5. Go to the **Network** tab to monitor network requests.
6. Look for an API call with the name signature in the network logs.
7. To analyze the error message, open the API in a new tab and search for the message where the failure occurred.
8. Identify the error message or reason for the failure.
**Example of error and resolution**
* **Error**: The WhatsApp list exceeds the character limit of 24.
* **Resolution**: Adjust the message content to comply with the character limit.
By following these steps, you can determine if the issue is related to the bot configuration or requires escalation to the platform or Meta team.
### Additional Tips
By following these guidelines, you can effectively troubleshoot and resolve message failures to ensure continuous and reliable communication through WhatsApp, Facebook, and Instagram channels.
* **Check configurations**: Ensure that all configurations related to the specific channel are correct and up-to-date.
* **Monitor network stability**: Network issues can cause intermittent message failures. Ensure stable network connectivity.
* **Update permissions**: Verify that all required permissions for the Yellow.ai platform and specific channels are properly set.
---
## Track user interaction with links in Chatbot components
You can monitor user interactions within the widget by tracking clicks on links within text messages (message-hyperlink-clicked), card buttons (card-cta-clicked), and banner buttons (banner-cta-clicked). When a user clicks on any of these components, an event is triggered, and the relevant information is stored in the **Event** column for analysis and insights.
To track link clicks in Chatbot components, follow these steps:
1. Go to **Insights** > **Data Explorer** > **User engagement events**.
2. Under Events table, you can view the user intearction (message-hyperlink-clicked, card-cta-clicked, and banner-cta-clicked).
---
## Building custom apps with YApps SDK
## Introduction
The YApps SDK enables the integration of custom applications within the Yellow Cloud platform. These apps are embedded as iframes within the parent application, allowing for extended functionalities such as customer management, custom visualizations, and dynamic workflows. The SDK ensures secure communication between the parent app and custom apps while controlling embedding permissions and interactions.
## Building and deploying a custom app
This guide provides a step-by-step process for building and deploying a custom app named `color-picker` for a customer named `bluewall`.
## Deployment methods
Custom apps can be deployed using one of the following methods:
### 1. In-House deployment (Using yellow cloud infrastructure)
#### Step 1: Develop the custom app
To develop a custom app, follow these steps:
1. Clone the repository: `yellowdotai/chat-components`
2. Navigate to `yellowdotai/chat-components/views/yapps/`
3. Create a new folder with the customer name (`bluewall` in this case).
4. Place all the customer’s custom apps within this folder.
**Example directory structure:**
```
yellowdotai/chat-components/views/yapps/bluewall/color-picker
```
#### Step 2: Build the Custom App
1. Choose a tech stack such as React, Angular, or Vanilla JavaScript.
2. Ensure that the final build files are stored inside the `dist/` folder within the app directory.
3. Use a bundler such as Webpack or Vite for optimized builds.
4. Minify and optimize assets to reduce load time.
5. Implement cross-origin isolation to prevent security vulnerabilities.
#### Step 3: Deployment & Access
1. Create a Pull Request (PR) and submit it for review to the repository owners.
2. Use Jenkins CI/CD pipelines to automate the deployment.
3. Perform both static and dynamic security testing before merging the PR.
4. Deploy the custom app and access it using the following URL format:
```
https://app.yellowmessenger.com/components/{customerName}/{appName}
```
**Example:**
```
https://app.yellowmessenger.com/components/bluewall/color-picker
```
### 2. On-Prem deployment (Customer’s infrastructure)
- The app is hosted on the customer’s infrastructure instead of Yellow Cloud.
- The YApps SDK must be included using the following CDN:
```
https://cdn.yellowmessenger.com/yapps-sdk/v1.0.0/widget.js
```
- Ensure that the app is deployed to a publicly accessible URL.
- Implement strict security measures such as Content Security Policy (CSP) headers to prevent cross-site scripting (XSS) attacks.
- Enforce HTTPS and TLS encryption for secure communication.
-----
## Using the YApps SDK
The YApps SDK provides methods that allow custom apps to securely interact with the Yellow Cloud platform.
### Importing the SDK
To use the SDK in your custom app, import it as follows:
```javascript
const yAppWidget = new YAppWidget();
```
### Available Methods
#### 1. Ticket Methods
**Fetch ticket details**:
```javascript
const ticket = await yAppWidget.getTicket();
```
#### 2. Ticket Custom Field Methods
**Fetch ticket custom fields**:
```javascript
const customFields = await yAppWidget.getTicketCF();
```
**Update ticket custom fields**:
```javascript
await yAppWidget.updateTicketCF({ key: "value" });
```
**Disable a custom field**:
```javascript
await yAppWidget.disableTicketCF("custom_field_1");
```
**Enable a custom field**:
```javascript
await yAppWidget.enableTicketCF("custom_field_1");
```
#### 3. Agent Methods
**Fetch agent details**:
```javascript
const agent = await yAppWidget.getAgent();
```
## Testing the Custom App on Cloud
After development, test the app by adding it as a custom app in the sandbox or staging environment of the customer’s bot on the Yellow Cloud platform.
## Custom App Configuration
The `custom-app-config` endpoint allows for the management of custom app settings via API requests (GET, POST, PATCH, DELETE).
### Example cURL request:
```sh
curl --location 'https://${regionCode}.cloud.yellow.ai/api/agents/settings/custom-app-config?bot=${botId}' \
--header 'Cookie: ym_xid=${ymXid}' \
--header 'Content-Type: application/json' \
--data '{
"description": "Color Picker",
"defaultContext": [],
"enabled": true,
"name": "bluewall color picker",
"url": "https://app.yellowmessenger.com/components/bluewall/color-picker",
"iconUrl": "https://cdn.yellowmessenger.com/assets/bluewall-logo.png",
"trigger": "live-forever",
"type": "ephemeral",
"location": "inbox.email.ticket.sidebar"
}'
```
### Configuration Properties Explained
- `description`: A brief summary of the app’s purpose.
- `defaultContext`: Context parameters to pass to the app. Leave empty if not needed.
- `enabled`: Boolean flag to enable (`true`) or disable (`false`) the app.
- `name`: Display name of the custom app.
- `url`: The endpoint where the app is hosted.
- `iconUrl`: URL for the app icon (must be publicly accessible).
- `trigger`: Defines how the app is activated (e.g., click, hover). Leave empty for now.
- `type`:
- `ephemeral`: Displays the app in the right sidebar of email or chat tickets.
- `persistent`: Runs in the background without a visible UI.
- `location`: Determines where the app is displayed (e.g., `inbox.email.ticket.sidebar`).
After successful testing, update the configuration for production deployment.
## Deploying to production
To deploy the custom app to production, follow these best practices:
- Automate deployment using Jenkins or GitHub Actions.
- Implement rollback strategies to revert changes in case of deployment failures.
- Use monitoring tools such as Prometheus and Grafana for logging and tracking performance.
- Apply API rate limiting and other security measures to protect against excessive API calls.
-----
The YApps SDK provides a structured and secure approach to building, deploying, and integrating custom applications on the Yellow Cloud platform. By following these best practices, developers can ensure a seamless and efficient extension of platform functionalities while maintaining high security and performance standards.
---
## Not receiving emails from Yellow.ai
If you're not receiving emails from the Yellow\.ai platform, follow the steps below to identify and resolve the issue.
### Step 1: Check if the Issue Is Isolated
Determine whether the issue is specific to you or affecting others in your organization.
* Ask colleagues if they are receiving Yellow\.ai emails.
* If you are affected, proceed to the next steps.
---
### Step 2: Check Your Spam or Junk Folder
Emails may be incorrectly flagged by your email client.
* Review your **Spam**, **Junk**, or **Promotions** folders.
* If you find Yellow\.ai emails there, mark them as **Not Spam** to prevent future filtering.
---
### Step 3: Try a Different Network
Some networks may restrict or block certain emails.
* Switch from your work network to **mobile data** or **home Wi-Fi**.
* Check if emails arrive when connected to a different network.
---
### Step 4: Verify with Your IT or Security Team
If the issue persists across networks, contact your IT or security team to confirm:
* Whether **firewall rules or email security filters** are blocking messages from Yellow\.ai.
* If **Yellow\.ai’s email IP addresses** are whitelisted.
> You can request the IP list by emailing [support@yellow.ai](mailto:support@yellow.ai).
---
### Step 5: Contact Yellow\.ai Support
If none of the above steps resolve the issue, reach out to [support@yellow.ai](mailto:support@yellow.ai). Include the following details to help us assist you faster:
* **Bot ID**
* **Issue start time** (approximate date/time when you stopped receiving emails)
* **Troubleshooting steps you've already tried**
---
> **Tip:** Keeping your IT team looped in while contacting support can speed up resolution, especially for email delivery issues involving firewalls or filters.
---
## Resolving Template Sync Issues Between Meta and the App Platform
**FAQ: Resolving Template Sync Issues Between Meta and the App Platform**
**Q1: Why aren't templates created in Meta syncing automatically to the app platform?**
**A:** Templates created in Meta do not automatically sync to the app platform due to integration limitations. Manual entry is required to ensure templates are available for campaigns.
**Q2: How do I manually add a template to the app platform?**
**A:** To manually add a template, follow these steps:
1. **Create the Template in Meta:**
- Use your WhatsApp Business Account (WABA) access to create the template in Meta.
2. **Open the Engagement Module in the App Platform:**
- Go to the engagement module and select "Create Campaign."
3. **Set Up a Test Campaign:**
- Choose a test audience and segment.
- Skip the sender’s field mapping option.
4. **Add the Template Manually:**
- When prompted to select a template, note that the Meta-created template will not appear.
- Click "Add Template" to enter it manually.
5. **Enter Template Details:**
- **Template Name:** Enter the name in lowercase (copy and paste from Meta).
- **Content:** Copy and paste the content exactly as it appears in Meta, including all spacing.
- **Namespace:** Obtain from Meta under the "Manage Template" options.
- **Parameters:** Enter the number of parameters used in the template.
- **Media:** Check if the template includes media and select the appropriate media type.
- **Quick Replies:** Specify the number of Quick Reply (QR) buttons and choose between QR or Call to Action (CTA) buttons.
- **Language:** Set the language according to the template (e.g., "en" for English, "hi" for Hindi).
**Q3: What should I do if the manual addition of the template does not work?**
**A:** If the manual addition fails:
- Double-check all details for accuracy.
- Verify that all required fields are filled correctly.
- Contact our support team for further assistance.
**Q4: Is there a way to automate or improve the sync process?**
**A4:** Currently, automatic syncing is not available. Manual entry is necessary until improvements are made to the integration system. Watch for updates on potential enhancements to the sync process.
---
## Email outbound domain authentication
- From the bulk email campaign account created for the brand, we will send something called ‘CNAME’ records to the mail ID suggested by the brand. CNAME records are a type of DNS records.
- DNS records are like text instructions available in the DNS server (the view of this is possible in the registrar account of the brand such as GoDady account of the brand). In certain cases, instead of CNAMEs, TXT and MX records will be generated for domain authentication.
- These DNS records tell what IP address is associated with what domains.
- By performing domain authentication, we map an IP address to the domains/subdomains of the brand.
- The CNAME records sent by us to the brand should be manually added by the brand in their DNS/ domain registrar portal.
- It takes upto 48 hours for the domain to be authenticated or rejected.
:::note
After the Domain authentication setup, we do reverse DNS. Reverse DNS is the opposite of domain auth , that is, connect the domain to the IP address.
:::
---
## Exclude opted-out users from campaigns
Enhance your campaign targeting by excluding users who have opted out. Learn how to ensure your messages reach the right audience while respecting user preferences.
## Store opt-out status through converstions
1. [Train an utterance](https://docs.yellow.ai/docs/platform_concepts/studio/train/intents#add-intents-and-utterances) with the keywords such as "DND" and "unsubscribe".
i. Navigate to **Automation** > **Train**.
ii. Click **Add new intent**.
iii. Provide a relevant name for the intent and add "DND" and "unsubscribe" as Uttrences.
iv. Click **Add** to save the intent.
2. [Set up a flow to trigger based on the intent](https://docs.yellow.ai/docs/platform_concepts/studio/train/intents#map-intents-to-flows) and choose the relevant intent.
3. Use the [Variable node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/variables-node) to [update the relevant user property](https://docs.yellow.ai/docs/platform_concepts/engagement/cdp/user_data/store_conv_data), in the following example, the `campaignOptIn` property is set to `false`. This ensures that the customer's optout status is captured and stored in User 360.
4. [Create a user segment](https://docs.yellow.ai/docs/platform_concepts/engagement/cdp/user_data_segments/segments_overview) excluding opted-out users.
Add a condition to include users whose `campaignOptIn` status is `true. `Use this updated property as a condition in segment targeting to exclude users who have opted for DND from receiving further campaign messages.
5. When [setting up your campaign](https://docs.yellow.ai/docs/platform_concepts/engagement/outbound/outbound-campaigns/run-campaign), make sure to exclude opted-out users using the segment you created. This ensures that users who have opted for "STOP" or "DND" will not receive any further campaign messages.
---
## Use cases for Shopify event-driven campaigns
## Cart abandonment recovery campaign
In an online store on Shopify, you notice that some customers abandon their shopping carts during the checkout process. To recover those potential sales, set up a Flow campaign to automatically send reminders to users who have abandoned their shopping carts on your Shopify store.
**Entry trigger**: `shopifyCartCreate` event
**Exception to trigger notification**: `ShopifyCheckoutCreated` event
**Flow configuration**:
1. **Trigger the flow**: Initiate the campaign when a user adds items to their cart, identify it using the `shopifyCartCreate` event.
2. **Wait condition**: Check if the user has completed the purchase by waiting for the `ShopifyCheckoutCreated` event. Set time delay, say 10 min. If no `ShopifyCheckoutCreated` event is detected within 10 min, proceed to the next step.
3. **Send abandonment reminder**: If the user has not completed the purchase within the specified time, send a WhatsApp notification. Here is a sample message:
- *Sample Notification Message:* "Hello [User's Name], we noticed you left some wonderful items in your cart. 🛒 Don't miss out on these great finds! Tap here to complete your purchase: [Checkout Link]. Thank you for choosing our store!"
---
## Guidelines to design your AI Agent
AI agents are smarter and more flexible than old rule-based bots. Instead of following fixed scripts, they can understand context, make decisions, and act on their own. To build an effective AI agent, you need clear goals, the right setup, and ongoing improvements.
## Key Practices
### 1. Set the Purpose and Persona
Decide what role the agent will play.
- Define its **tone and style** (helpful, professional, friendly, etc.).
- Match the agent’s role to your business need (support expert, sales guide, knowledge assistant).
- Link the purpose to a clear outcome, like faster service or fewer escalations.
### 2. Focus on Use Cases, Not Scripts
Forget designing step-by-step flows.
- Think in terms of **goals**: “Answer billing questions,” “Suggest the right plan,” “Book a meeting.”
- The agent will build conversations around these goals using AI.
### 3. Provide Knowledge and Context
Give the agent access to the right information.
- Connect to your **knowledge base** for FAQs and guides.
- Link to business systems (CRM, ERP, HR, ticketing) so it can complete tasks.
- Add **rules, triggers, and variables** to keep conversations accurate.
### 4. Add Guardrails
AI agents should work freely but with limits.
- Set **handover to humans** for complex cases.
- Use **fallbacks and validations** to avoid errors.
- Monitor with tools to understand how the agent makes decisions.
### 5. Improve with Analytics
Keep refining your agent.
- Track performance with metrics like **containment, resolution, CSAT, and sentiment**.
- Review where it works well and where it needs support.
- Update prompts, integrations, or style based on insights.
---
## Alias name for agents
Maintaining confidentiality is crucial in chat conversations. To ensure privacy, you can display an alias name instead of an agent's actual name. This feature enables you to record information in reports while remaining anonymous. For security reasons, the system will store the agent's real name, but only the alias name will be visible on the widget. If you don't provide an alias name, the system will display the real name.
Here are some scenarios where you can use this feature:
## 1. Add an alias name to be displayed on the chat widget
> Only **Inbox admins** can modify agent details.
When customers connect with an agent, the alias name will appear on the chat screen.
1. Open **Inbox** > **Settings** > **Team** > **Agents**.
2. Select the agent you want to assign an alias name to.
3. Enter **Alias name** and click **Update**.
The **widget** and **preview** screens will show the alias name when available:
----
## 2. Display alias name in the chat when the agent is connected
> This feature is available to **Bot developers** with access to create flows, provided that the **Inbox admin** has configured the alias names.
You can customize the message with alias name and display it to the bot user after they are connected to an agent.
1. Go to **Automation** and open the flow where agent support is [configured](https://docs.yellow.ai/docs/platform_concepts/inbox/inbox_setup/inboxdemo).
2. In the [Raise ticket](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/raise-ticket) node, manually enter the required message and variables in the **Message after ticket assignment** field.
:::info
You can use the `{{agentAliasName}}` variable to display the alias name. It will only be available if the agent's alias name is configured on the [agent settings](https://docs.yellow.ai/docs/platform_concepts/inbox/inbox-settings/team/agents) page.
:::
## 3. Access alias name through canned response on chats/tickets
> **Inbox admins** can create canned responses that **Inbox agents** can use while conversing with customers via live chat or email.
**For Inbox admins:**
1. Refer to [this](https://docs.yellow.ai/docs/platform_concepts/inbox/inbox-settings/productivitytools/canned-responses) procedure to create canned response.
2. Add a tag and use `{{agent.aliasname}}` in the response.
**For Inbox agents:**
On the chat/email screen, enter # followed by the tag to select the alias name that can be sent to the customer.
---
## Checking Ticket History (Email Ticket or Live Chat) of a Specific Customer
## Use Case
The **View Recent Activity** feature in the Yellow.ai Inbox Module enables agents to review the historical support interactions—both email tickets and live chats—associated with a specific customer. This feature displays previously raised tickets along with key metadata such as agent name, ticket priority, and current status. Accessing this information allows agents to better understand recurring issues and provide more accurate and contextual support.
**Related Use Cases**
1. How to view customer profile and activity using User 360.
2. How to tag and manage user data within the Yellow.ai platform.
3. How to escalate recurring issues based on ticket history.
:::note
**Prerequisites**:
Ensure you have appropriate access to the following sections of the Yellow.ai dashboard:
- **Email Tickets**: Inbox → Tickets
- **Live Chats**: Inbox → Chats
:::
## Steps to Check Ticket History
### 1. Open the Email Ticket or Live Chat
- Navigate to the **Inbox** module.
- Select either:
- An email ticket from **Inbox → Tickets**, or
- A live chat from **Inbox → Chats**.
### 2. Locate Customer Details
- At the top-right corner of the ticket or chat interface, locate the section displaying customer information.
- This panel contains user metadata and interaction context.
### 3. Click on “View Recent Activity”
- Within the customer details panel, click the **"View Recent Activity"** link.
- This will open a list of all previous tickets or chats raised by the customer.
### 4. Review Ticket History
- The list will include:
- Ticket titles
- Assigned agent names
- Priority levels
- Current status of each ticket (e.g., Resolved, Open)
- To examine a specific ticket in detail:
- Click on the ticket title. This will redirect you to that ticket’s detailed view.
### 5. Repeat for Live Chats (if applicable)
- The same procedure can be used for reviewing live chat history.
- Navigate to **Inbox → Chats**, select a customer interaction, and follow the steps above to access their chat history via **View Recent Activity**.
## Expected Outcome
Agents can view a customer's entire ticket or chat history, improving their ability to respond to ongoing or recurring issues. By accessing past support interactions, agents are better equipped to provide efficient, context-aware resolutions.
The "View Recent Activity" feature is a critical tool for maintaining continuity in customer support and enabling proactive issue resolution.
---
## Automatically resolving spam email tickets
In cloud bots, we can resolve email tickets if the ticket has been raised by a particular email ID recognized as spam.
## Prerequisites to resolve
- Ensure Ticket-created event is set up.
- Maintain a list of email addresses identified as spam.
- Ensure you have the API endpoint and necessary credentials to resolve tickets.
## Steps to resolve
1. **Create the Ticket-created Event**:
- Go to **Automation > Events > Custom Events**.
- Click on Add Event and add `ticket-created`.
2. **Create a Flow from Scratch:**
- Go to Build and create a new flow.
- In the start node, select the trigger type Event and choose `ticket-created`.
- This flow will be triggered as soon as a ticket gets created in the email tickets section.
3. Get the Incoming Email from the `ticket-created` Event:
- The ticket-created event contains the following data that can be accessed as needed:
```
{
"event": {
"code": "ticket-created",
"emailThread": {
"_id": "669baa6ac95bf92836c2486e",
"messageIds": [
""
],
"botId": "x1694470802970",
"initiatorMail": "bhavana.thakkelapati@yellow.ai",
"fromMail": "bhavana.thakkelapati@yellow.ai",
"to": [
{
"address": "testyellowdotai@gmail.com"
}
],
"subject": "testing",
"replyEmail": "testyellowdotai@gmail.com"
},
"ticketData": {
"id": 5315,
"ticketId": 332,
"botId": "x1694470802970",
"uid": "669baa6ac95bf92836c2486e",
"source": "",
"contactId": "878e8e26-f225-46c6-a20a-de6066de8eb2",
"subject": "testing",
"lastMessage": null,
"priority": "MEDIUM",
"statusId": 1,
"status": {
"id": 1,
"createdAt": "0001-01-01T00:00:00Z",
"updatedAt": "0001-01-01T00:00:00Z",
"deletedAt": null,
"name": "OPEN",
"settingId": null
},
"internalStatus": null,
"groupCode": null,
"xmpp": null,
"dueDate": null,
"responded": false,
"firstRespondedTime": null,
"firstResponseDuration": null,
"firstResponseDurationCreated": null,
"assignedTo": null,
"assignedAgent": {
"id": 0,
"botId": "",
"agentId": "",
"currentAssignedTicketCount": null,
"maxTicketConcurrency": 0,
"lastTicketAssignedTime": null
},
"assignedTime": null,
"resolvedTime": null,
"assignedByAdmin": false,
"manualAssignment": false,
"lastUserMessageTime": null,
"lastAgentMessageTime": null,
"lastBotMessageTime": null,
"averageResponseTime": 0,
"replyCount": 0,
"userReplyCount": 0,
"customFields": {},
"ticketType": 0,
"createdAt": "2024-07-20T12:15:39.583188Z",
"updatedAt": "2024-07-20T12:15:39.583188Z",
"deletedAt": null,
"tags": [
{
"id": 4,
"createdAt": "0001-01-01T00:00:00Z",
"updatedAt": "0001-01-01T00:00:00Z",
"deletedAt": null,
"botId": "",
"code": "auto_assignment_pending",
"name": "auto_assignment_pending",
"settingId": null,
"tickets": null
}
],
"parent": false,
"parentTicketId": null,
"contact": {
"contactId": "878e8e26-f225-46c6-a20a-de6066de8eb2",
"primaryEmail": "bhavana.thakkelapati@yellow.ai",
"botId": "x1694470802970",
"firstName": "Bhavana",
"lastName": "Thakkelapati",
"uids": [
{
"botId": "x1694470802970",
"uid": "6584fe9e27d39a938d2b174a",
"channelName": "email"
}
]
},
"slaId": 0,
"slaPause": {
"id": 0,
"createdAt": "0001-01-01T00:00:00Z",
"updatedAt": "0001-01-01T00:00:00Z",
"deletedAt": null,
"ticketIdPk": 0,
"paused": false
},
"slaActivity": null,
"activityLog": null,
"frtBreached": 0,
"ertBreaches": 0,
"ertAchievements": 0,
"rtBreached": 0,
"slaAchievement": "",
"transferred": false,
"reopened": false,
"reopenedCount": 0,
"reopenedBy": null,
"lastReopenedTime": null,
"agentFirstResponseTimeRecorded": false,
"lastAssignmentId": null,
"agentTicketHandlingTimeStartedAt": null,
"handlingTime": null,
"transferCount": 0,
"sourceEmail": "testyellowdotai@gmail.com",
"collaborators": null,
"resolutionTarget": "",
"resolutionDueTime": null,
"firstResponseTarget": "",
"firstResponseDueTime": null,
"collaboratorsUserNames": null,
"agentName": "",
"agentAliasName": "",
"agentEmail": "",
"reopenedAgentEmail": "",
"resolutionDurationCreate": 0,
"resolutionDurationAssigned": 0,
"tagNames": null,
"isNewTicket": true,
"unreadMsgCount": 0,
"highlight": null,
"cdpId": "x1694470802970_qX6KmO7eEGUy6KAWSHW_V",
"sessionId": "669baa6ae58187819623d88c",
"es_doc_props": null
}
},
"medium": "message",
"type": "event"
}
```
4. **Get the Initiator Email**: Extract the user email ID from the event using `{{{data.event.emailThread.initiatorMail}}}`.
5. **Check for Spam Email**: Compare the extracted email ID with your spam emails list. If the email is in the spam list, proceed to resolve the email ticket.
6. Resolve the Email Ticket:
**API to resolve the email ticket**
```
curl --location --request PUT 'https://cloud.yellow.ai/api/ticketing/ticket/23?botId=x1667286708237' \
--header 'Content-Type: application/json' \
--header 'x-api-key: TUl4bVHPpUm8hYan-7V9nb8UvuoCyIi_OdRo2-yS' \
--header 'Origin: https://cloud.yellow.ai' \
--data '{
"statusId": 2 // The status ID 2 indicates the resolved status of the email ticket.
}'
```
****
****
---
## Enable close ticket options for agents in app bot
When agents cannot see the *Close ticket options* on the app screen while closing tickets, follow these steps:
:::note
**Prerequisite**:
Add **group codes** to the close ticket options based on agent groups.
:::
1. Check for groups: Verify if there are any groups created within the system.
2. Agent group assignment: Ensure that the agent experiencing the issue is added to a group. If the agent is not in a group, add them to the appropriate group.
3. Verify close ticket options:
- If the agent already belongs to a group, check the Close ticket options.
- Review the groups assigned to each Close ticket option.
- Add the relevant group names to the settings for each Close ticket option.
4. Visibility settings: Ensure the checkbox for Close ticket options to be visible while resolving tickets is ticked.
:::info
Only the agents added under a particular group can access the close ticket options on the ticket interface while resolving the ticket.
:::
:::note
In Cloud Bot, the Close ticket options are covered under custom fields of Hierarchical type.
:::
---
## CSAT in chat archives report
To include CSAT scores in the chat archives report, follow these steps:
1. Ensure that you **capture** the CSAT scores during the conversation and store them in appropriate variables.
:::info
Click [here](https://docs.yellow.ai/docs/cookbooks/insights/botagentfedback) to learn more on creating flows to fetch CSAT.
:::
2. Use the following **API request**:
```
url = 'https://cloud.yellow.ai/api/agents/tickets/update_csat_score_from_bot'
headers = {
'Content-Type': 'application/json'
}
bot_id = 'x1623067352191'
ticket_id = '100733'
ticket_csat_score = 1
agent_csat_score = 5
data = {
'botId': bot_id,
'ticketId': ticket_id,
'csatData': {
'ticketCsatScore': ticket_csat_score,
'agentCsatScore': agent_csat_score
}
}
response = requests.post(url, headers=headers, data=json.dumps(data))
# Handle the response as needed
```
Modify the API request by providing the correct values for the variables:
- Replace `botId`: "x1623067352191" with the actual bot ID.
- Replace `ticketId`: "100733" with the relevant ticket ID.
- Replace `ticketCsatScore`: 1 with bot CSAT score you have captured.
The *ticketCsatScore* field in the API accepts the values 0, 1, or null, indicating the following:
- 1: The ticket has been solved.
- 0: The ticket remains unsolved.
- Null: No response was provided.
- Replace `agentCsatScore`: 5 with the corresponding CSAT score you have captured.
The *agentCsatScore* field in the API only accepts numerical values from 0 to 5. A score of 0 represents the lowest rating, while 5 represents the highest rating.
:::note
You can find the CSAT scores in the [Chat archive reports](https://docs.yellow.ai/docs/platform_concepts/inbox/analytics-reports/reports/chats/chat-archives-report) under the fields **ticket_csat** and **agent_rating**.
:::
---
## Custom Usecases
Steps are mentioned to resolve each of the commonly encountered use cases:
## 1. How to assign a ticket to a particular group with a particular tag
Follow the below steps to assign a ticket to a group by adding any tag:
1. In Inbox settings, create a [group](https://docs.yellow.ai/docs/platform_concepts/inbox/inbox-settings/team/groups#1-add-a-new-agent-group) and [tag](https://docs.yellow.ai/docs/platform_concepts/inbox/inbox-settings/workflows/tags).
2. Use the Raise ticket action node for each group.
3. Pass the information in the advanced settings of the ticket under Department and Tag.
> Click [here](https://docs.yellow.ai/docs/platform_concepts/inbox/inbox-settings/team/groups#11--use-groups-in-the-raise-ticket-node) for more information.
-----
## 2. How to set values coming from each channel on the tickets
Follow the below steps to set values coming from each channel:
1. Use a channel filter to set variables.
2. Create global variables and set those variables.
> With either variables coming from payload like `{{{profile.payload.< key_name in payload >}}}` Or `{{{sender}}}` in case of WhatsApp
4. Pass the same variables in the raise ticket action node.
-------
## 3. How to build this flow - For failed tickets, the query and contact must be stored and an email has to be sent
Follow the below steps to store user details for failed tickets:
1. In the raise ticket action node on the error node, use a send email action node.
2. Create a database and use a database node to insert the ticket details into the database.
--------
## 4. How to Visualize a team's CSAT values on the yellow.ai platform(Data explorer)
Currently, the Inbox CSAT values are not available for visualization (widgets/graphs). Agent CSAT values are found in **Data explorer** > **Chat tickets**.
You can create a custom CSAT bot flow (on Automation). Store the custom CSAT data in a database, and create a visualisation of your preference in Data Explorer.
Click [here](https://docs.yellow.ai/docs/cookbooks/insights/botagentfedback) for more details.
**Sample flow:**
-------
## 5. What happens when the Group is configured with email IDs(for email communications) but is used in raise ticket node
- Consider a use case where the agent groups-Esclations (with email ID as abc@company.com) is added in the inbox groups settings. This group will be visible on the [Raise ticket node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/raise-ticket)- Advance options. For example, the Escalation group is selected on the Raise ticket node.
- All the support requests that are triggered through this particular flow will be assigned to the Escalation group **live chats**. These support requests will be found in the **Chats** tab and not in the **Tickets** tab.
---
## 6. How to pass hierarchical custom fields in raise ticket node
You can pass hierarchical custom fields in an array variable (this array variable has to be created in a function).
**Array variable syntax:**
```
[
{
"id": "id6d80e018eb471-1687697102772",
"name": "Typeone",
"levelName": "Sub Category"
},
{
"id": "ida4564067aff73-1687697129156",
"name": "TypeTwo",
"levelName": "Sub Category"
}
]
```
---
## Data could not be loaded. Please update or try again later.” (Inbox Monitor page)
This error appears in the **Monitor** tab of the Yellow\.ai dashboard and prevents viewing analytics and performance metrics. In this case:
* Monitor tab displays a persistent error message.
* Key metrics such as assigned chats, resolved chats, and handling time are not visible.
* Developer tools show failed API calls with 400 Bad Request errors.
## Possible Cause
This issue commonly occurs when the **bot's timezone is not set or incorrectly configured**. An invalid or missing timezone causes platform analytics APIs to fail, preventing data from loading.
## Prerequisites
Before proceeding:
* Ensure you have access to the Yellow\.ai dashboard.
* Open your browser’s developer tools (Chrome, Edge, or Firefox).
## Steps to Troubleshoot and Fix
### 1. Open the Monitor Tab and Developer Tools
* On the left navigation bar, go to **Inbox** > **Monitor**
* Open the browser's **Developer Tools**:
* Windows/Linux: Press `F12` or `Ctrl + Shift + I`
* macOS: Press `Cmd + Option + I`
* Switch to the **Network** tab.
### 2. Check for 400 Bad Request Errors
* While the Monitor tab loads, observe the network requests.
* Look for any failing requests with a **400 Bad Request** status.
> These usually indicate an issue with the API request, often related to timezone configuration.
### 3. Update the Bot’s Timezone
* Go to the **bot configuration** settings. Follow this guide to set or update the timezone:
[🔗 Modify Bot Configuration – Yellow.ai Docs](https://docs.yellow.ai/docs/platform_concepts/get_started/modify-bot-configuration#addupdate-ai-agent-information)
* Make sure the timezone field is populated with a valid timezone (e.g., `Asia/Kolkata`, `America/New_York`).
### 4. Refresh and Revalidate
* After saving the bot configuration:
* Refresh the Yellow\.ai dashboard.
* Navigate back to the **Monitor** tab.
* The analytics data should now load correctly.
:::info
Additional Information:
* Ensure the bot has proper permissions and the latest configuration is deployed.
* If you're using a custom domain or proxy, verify there are no request blockers in place.
* If issues persist, capture the network log and contact Yellow\.ai support.
:::
---
## Dyte Event Integration in Cloud Web Bots
When the video call feature is enabled in the **Raise Ticket** node, the bot receives an event called `dyte-event`. This event has multiple sub-events that allow the bot to send messages or follow up with clients accordingly.
:::note
**Prerequisites**
- **Chat with Agent Flow**: Ensure that the chat flow is set up to enable communication with an agent.
- **Video Call Feature**: The video call feature must be activated in the bot configuration.
:::
## Steps to use dyte event
1. Navigate to **Automation > Flows**. Open the **Raise Ticket** node > **Advance settings**.
2. Select the options for **Voice Call** and **SIP Call**.
****
****
3. **Initiate Video Call**:
- Once these settings are configured, a call symbol will appear beside the **Transfer** and **Resolve** buttons when the chat is assigned to you within the **Inbox** module.
- Click on the call symbol to initiate a video call with the end user.
****
4. After the video call is connected, the bot will receive a `dyte-event`. This event includes several sub-events that can be used to trigger further actions.
## Sub-Events in Dyte Event
- **meeting.started**: Triggered when the meeting starts.
- **meeting.participantJoined**: Triggered when a participant joins the meeting.
- **recording.statusUpdate**: Triggered to provide updates on the recording status.
- **meeting.participantLeft**: Triggered when a participant leaves the meeting.
- **meeting.ended**: Triggered when the meeting ends.
---
## Resolving "Data could not be loaded" Error in the Yellow.ai Monitor Tab
## Use Case
In the Yellow.ai dashboard, users may encounter the error message:
**"Data could not be loaded. Please update or try again later."**
This typically occurs in the **Monitor** tab, preventing the display of important performance metrics such as:
- Assigned chats
- Resolved chats
- Missed chats
- First response time
- Handling time
This issue impacts the ability to monitor agent performance and manage live chat operations, often requiring teams to resort to manual data extraction.
**Related Questions and Symptoms**
1. Why am I seeing "Data could not be loaded" in the Monitor tab?
2. How do I set the timezone for my Yellow.ai bot?
3. Why are platform APIs failing with 400 errors related to analytics?
:::note
**Prerequisites**:
Before proceeding with the resolution steps, ensure the following:
- You have access to the Yellow.ai dashboard.
- You are familiar with browser developer tools, particularly the **Network** tab.
:::
## Steps to Resolve
### 1. Access the Monitor Tab and Open Developer Tools
- Navigate to the Yellow.ai dashboard and go to the **Monitor** tab.
- Open the browser’s developer tools:
- In most browsers, this can be done by pressing `F12` or using the shortcut `Ctrl+Shift+I` (Windows/Linux) or `Cmd+Option+I` (Mac).
- Within the developer tools, go to the **Network** tab.
### 2. Check for 400 Bad Request Errors
- While the Monitor tab is attempting to load data, observe the network requests in the **Network** tab.
- Look for API requests that are failing with a **400 Bad Request** status code.
- These errors often indicate issues with request parameters, commonly due to a missing or incorrectly configured timezone.
### 3. Set or Update the Bot Timezone
- If 400 Bad Request errors are observed, it is likely that the bot’s timezone is not set or is misconfigured.
- Refer to the official Yellow.ai documentation to configure the timezone: [Modify Bot Configuration – Yellow.ai Documentation](https://docs.yellow.ai/docs/platform_concepts/get_started/modify-bot-configuration#addupdate-ai-agent-information)
- Follow the instructions in the section **Add/Update AI Agent Information**, ensuring that the **timezone** field is correctly specified (e.g., `"Asia/Kolkata"`, `"America/Toronto"`).
### 4. Verify Data in the Monitor Tab
- Once the timezone has been configured, refresh the Yellow.ai dashboard.
- Reopen the **Monitor** tab and verify if the performance metrics are now loading correctly.
## Expected Outcome
After configuring the bot's timezone correctly, the platform API requests should succeed. The Monitor tab will display performance data as expected, restoring visibility into key live chat metrics and agent productivity.
---
## Notify Agents when they are offline/busy/away
Whenever an agent is offline or busy or away and a user tries to contact the agent via the bot, an agent can be notified about the same through an email (or even via SMS, WhatsApp, or voice) by using an outbound notification node.
Follow the given steps to notify agents when they are offline/busy/away:
1. Create a global variable with the agent's email as a value.
2. Set email template in **Engage** > **Templates**.
3. Use outbound notification and set-up using the agent's email variable and email template.
4. Set events “ticket-opened”, “ticket-missed” and “ticket-queued” to active inside Event in Automation. Post this, the start trigger node needs to be configured with these events in the respective flow.
---
## Notify customers on agent unavailability when offline handling is enabled
:::info
**Prerequisite**: Enable **offline handling** settings as described [here](https://docs.yellow.ai/docs/platform_concepts/inbox/inbox-settings/workflows/offline-chat).
:::
When **Offline handling** is enabled and you want to inform customers that agents are currently unavailable and their queries will be addressed once an agent is back online, follow the steps below by picking your closest use-case:
## Notification for open and queued chats
1. Navigate to **Automation > Flows**, open the flow that includes the **Raise ticket** node.
2. Store the output of the **Raise ticket** node in a variable, as shown in the image.
3. Connect the error part of the **Raise ticket** node to a new node, which is responsible for displaying messages to the customer.
> When offline handling is enabled, the chat is not immediately answered, and the flow continues to the next node until an agent responds.
4. In the new flow, retrieve the status of the ticket by accessing the status value stored in the variable `{{{variables.raiseTicketObj.status}}}`.
5. Add a [condition node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/logic-nodes#1-condition) to your flow to identify the ticket status.
6. Depending on the ticket status identified in the condition node, you can connect the conditions to a Text node to display a relevant message addressing the customer.
> You can also fetch the ticket ID by using the variable: `{{{variables.activeTicketNumber}}}`
-----
## Notification for open chats (recommended)
1. Access the **Automation** section and navigate to **Events**.
2. Open the [Custom events](https://docs.yellow.ai/docs/platform_concepts/studio/events/event-hub) and click **+Add event**.
3. Provide the **name** `ticket-opened` and click **Create event**.
4. Ensure that the `ticket-open` event is **Active**. If not, make it Active by clicking on the three dots next to it.
5. [Create a new flow](https://docs.yellow.ai/docs/platform_concepts/studio/build/Flows/journeys) in the **Automation** > **Build**.
6. Within the flow, add a start trigger by clicking on the start node. Select **event** from the dropdown and set the value as `ticket-opened`.
7. Add a text node to display an acknowledgment to the customer, informing them to wait for a while.
----
## Expected behaviour after creating a flow to notify customers
`Assume all the agents are offline at the same time and a customer has requested to talk to an agent.`
`A live chat request is raised`
`The live chat appears in the "Open chats" section of the inbox`
`The customer waits on the chat screen`
`A message is displayed to the customer, stating the delay: "Your chat will be assigned as soon as we find an available agent. Please wait, and thank you for your patience"`
`When any agent in that group comes online and becomes available, the live chat is immediately assigned to them`
---
## Change the priority of the ticket and assign it to a different agent or a group
In this article, you will learn how to change the **priority** of a chat/email ticket and **transfer** it from one inbox agent to another.
----
#### Configure priority and group on the Raise ticket node
- While creating flows (on Automation) using [Raise ticket action node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/raise-ticket), the bot builder can assign a priority to the chat/email tickets. Tickets created through this flow will have the assigned **Priority**.
- You can configure Priority in the action node by enabling Advanced options. In the below example, all the tickets created will be assigned to the Complaints Department (configured in [group settings](https://docs.yellow.ai/docs/platform_concepts/inbox/inbox-settings/team/groups) and the priority is High.
----
To change the **Priority**/**Assignee**, follow the below steps:
#### Assign chat tickets to a different agent or group
:::note
Inbox Agent or Admins cannot change the priority of chat tickets.
:::
> Refer to [this doc](https://docs.yellow.ai/docs/platform_concepts/inbox/chats/chatscreen#2-user-details) to learn about chat screen and chat details.
1. Open any ongoing chat > **Details** and click **Transfer** (this option will be available based on the configuration of [custom fields](https://docs.yellow.ai/docs/platform_concepts/inbox/inbox-settings/workflows/chat_custom_fields).
2. Select the Agent/Group to which you want to transfer the ticket. Confirm the reassignment.
3. Your chat will be transferred to the selected inbox agent or the concerned group/team (tickets will be autoassigned to the agents in this group).
4. While re-opening the missed/resolved chats, Inbox Admins can select the **Priority** of the ticket and assign the ticket to a particular **Category/Agent**.
#### Change priority and assign email tickets to a different agent
> Refer to [this doc](https://docs.yellow.ai/docs/platform_concepts/inbox/tickets/emailticketstatus#2-status-transition-from-different-views) to learn about email ticket screen and statuses.
:::note
- Inbox Agent and Admins can change the priority of email tickets.
:::
1. Priority and Assignee can be changed from the email tickets page. Search for the required ticket and select the priority/assignee (group/agent) from the dropdown.
2. You can open the email ticket and view the details. Modify the Ticket Details (change the priority and assignee). These changes will be updated on the Activity log.
---
## Viewing Recent Activity in Inbox Chats/Tickets
## Use Case
The "View Recent Activity" feature within the Yellow.ai inbox module enables agents to monitor user-specific actions by tracking tickets raised on behalf of the user and any related updates to user property parameters. This ensures visibility into user behavior and historical data, aiding in better support and resolution management.
**Related Use Cases**
- How to use user property variables to store data in bot flows.
- Monitoring historical ticket data.
- Managing customer data through the User 360 profile.
:::note
**Prerequisites**:
- Access to the Yellow.ai dashboard with permissions to use the Inbox module.
- Familiarity with the concept of user properties and ticket handling within the Yellow.ai platform.
:::
## Steps to Use the Feature
### 1. Accessing the Inbox Chat Interface
- Navigate to the **Inbox** module in the Yellow.ai dashboard.
- Open any chat or ticket associated with a user.
### 2. Locating the "View Recent Activity" Option
- Within the agent chat interface, locate the **"View Recent Activity"** button.
- This button provides quick access to historical customer data that was shared during previous bot interactions.
### 3. Reviewing Recent User Properties
- Upon clicking **View Recent Activity**, a panel will display the user's recent activity.
- Only **user property variables**—i.e., data points explicitly stored using variables during the bot flow—will be shown here.
- These include details that were collected during earlier conversations and can be used to understand user intent and behavior at the time a ticket was raised.
### 4. Viewing Full Activity Log
- If additional information is needed, scroll down to find the **"View All Activity"** option.
- Click on this option to be redirected to the **User 360 - User Profile Page**.
### 5. Using the User 360 - User Profile Page
- This section provides a comprehensive view of all user-related data and activities.
- Agents can:
- View all property changes and ticket-related activities.
- Add relevant **tags** to enhance the user profile and improve future context handling.
- Use the built-in **search functionality** to quickly locate specific user properties.
### 6. Managing User Data
- To manage or remove user records, click on the **"Delete User"** button located at the top-right corner of the User 360 page.
- This action will delete the selected user and all associated activity data from the platform.
## Expected Outcome
Agents can efficiently trace a user’s journey, understand ticket contexts, and access relevant data points to facilitate better responses and decision-making. The feature also supports user data enrichment and cleanup via tagging and deletion options.
This feature streamlines agent workflows by centralizing user data, enabling faster resolution times and improved customer experience.
---
## Creating a Slack App for Internal Ticketing
To enable internal ticketing functionality on your agent's live chat screen, follow these steps:
1. **Create a new Slack app**: Go to the [Slack API page](https://api.slack.com/apps) and click on "Create New App".
2. **Configure app settings**:
- Select **From Scratch** and provide a name for your app.
- Choose the workspace where you want to deploy the app and click on **Create App**.
- Dashboard for the app opens up.
3. **Set up incoming webhooks**:
- Navigate to **Features** in the left sidebar and select **Incoming Webhooks**.
- Toggle **Activate Incoming Webhook** to turn it on.
4. **Configure event subscriptions**:
* Under **Features**, select **Event Subscriptions**.
* Enable events and provide a Request URL obtained from the Inbox Team.
* Click **Subscribe to bot events**.
* Subscribe to the following events:
* Channel Deleted
* Member Joined Channel
* Member Left Channel
* Message Channels
* Message Groups
* Click on **Save Changes**.
5. **OAuth and permissions**:
* Go to **OAuth and Permissions** to deploy the app in your Slack workspace.
* Click on **Install to Workspace** to generate the Bot User OAuth token required for internal ticketing.
* Allow access to the general channel or any specific channels where the app can post messages.
6. **Copy Bot User OAuth Token**: After installation, copy the Bot User OAuth Token, which typically starts with `xoxb-`. Paste this token in the Channels Page in cloud.yellow.ai under **Slack** > **Slack Tokens**.
7. **Add scopes**: Scroll down to the **Scopes** section and add the following scopes for the Bot User OAuth Token:
```
App Mentions: Read
Chat: Write
Channels: Write Invites
Channels: History
Channels: Read
Chat: Write Customize
Chat: Write Public
Files: Write
Groups: History
Groups: Read
Groups: Write
Groups: Write Invites
IM: History
IM: Read
IM: Write Invites
Metadata Message: Read
MPIM: History
MPIM: Read
MPIM: Write Invites
Usergroups: Read
Users: Read
Files: Read
Remote Files: Share
Remote Files: Write
```
8. **Reinstall the app**: Once all scopes are added, reinstall the app to your workspace by clicking on **Reinstall to Workspace**.
9. **Finalize configuration**: Your Slack app is now ready for use. Use the Bot User OAuth Token for [configuring internal ticketing](https://docs.yellow.ai/docs/platform_concepts/channelConfiguration/slack2#create-an-app-in-slack) on cloud.yellow.ai > **Channels > Slack**.
:::info
Refer to [this document](https://docs.yellow.ai/docs/platform_concepts/inbox/chats/internal-ticket) for guidance on using internal ticketing within the inbox.
:::
---
## Display message or sync data when a Live Chat is closed
When a customer initiates a live chat, an inbox agent takes on the task of resolving the query. Once the agent has resolved the query, they mark the chat as **Resolved**. This triggers the execution of the node connected to the **ticket closed** in the [raise ticket](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes#raise-ticket-outputs) node, which is followed by the other nodes connected to it.
After a chat has ended, you may want to perform actions like updating a database, calling an API, sending customer details to the CSM, or displaying promotional messages or products. However, you cannot connect the **ticket closed** part of the [raise ticket](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes#raise-ticket-outputs) node to both options simultaneously. In this case, you can use an **event** to identify the ticket closed and perform background actions on a different flow.
> If the [CSAT setting](https://docs.yellow.ai/docs/platform_concepts/inbox/inbox-settings/workflows/csat) is enabled, the system records the customer feedback on the agent before closing the chat.
To configure the system to automatically trigger an event when agents resolve a live chat, you need to manually enable it from the event hub and use it in the flows.
------
## Step 1: Attach nodes to ticket closed
1. To attach nodes to ticket closed, connect the **Raise ticket** > **Ticket closed** with the nodes you want to execute. This will get triggered after the ticket is closed.
:::info
- This step is recommended but not mandatory, it is required to make sure that the flow is completed and the user is intimidated that the ticket is closed.
- You can also add options in this flow that connects to other flows to improve your user experience.
:::
-----
## Step 2: Activate ticket-closed event
To identify that the inbox agent has closed a ticket you must enable **Ticket closed** event. Follow these steps:
1. Go to **Automation** > **Events** > **Inbox** and search for `ticket-closed`.
2. Click the three dots icon and select **Activate** to activate the event.
-----
## Step 3: Trigger flows after a ticket is resolved
You can design flows that can be triggered when **Ticket closed event** is identified. Follow these steps:
1. Create a new [flow](https://docs.yellow.ai/docs/platform_concepts/studio/build/Flows/journeys).
2. By clicking **Start** node you can set when the flow gets triggered. Set it to **Event** and select the value as **ticket-closed**.
3. To provide a personalized response from the bot when a ticket is closed, add [nodes](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes) to the flow that are designed to execute specific tasks. The flow will automatically run whenever a ticket is closed.
-----
### Use-cases of ticket-closed event
A few examples of the flows that can be run after the ticket is closed.
> You can add one or more flows with start trigger as `ticket-closed`. All these flows will run simultaneously.
1. **Update a database/CRM with ticket details.**
2. **Create a logic to filter the user data based on the type of query raised and send it to a CRM/Database.**
3. **Hit an API once the ticket is closed.**
4. **Send a promotional messsage.**
5. **Schedule a follow up interview.**
---
## Flow to connect with an agent without asking for any information from the user
Follow the below steps to transfer the chat to an agent without asking for any information from the user:
1. **Name** and **Query** are the mandatory fields to be passed into Raise ticket node. To create a flow that does not ask user for any of the information, create two **global variables** (click [here](https://docs.yellow.ai/docs/platform_concepts/studio/build/bot-variables#3-create-a-variable) to learn how) for storing names and queries with some dummy values (the dummy name and query won’t be displayed to the user, it will be displayed to the live agent).
2. Create a simple flow and directly connect Raise ticket node to the start node.
3. Pass the same variables in the [Raise ticket action node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/raise-ticket).
4. This flow can end with **Ticket closed** and **Error** connected to a [Message](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/message-nodes1/message-nodes) node.
---
## Configuring call URLs
The **Video Call URL** is a meet link with a built-in authentication token. Clicking on this URL allows individuals to join the call effortlessly.
This URL is generated and sent to every participant in the call.
- For agents, it is readily available on the UI along with their authentication token.
- For end users accessing Yellow.ai via the widget, the option to join a video call(URL) is found as a call button on their UI.
- For end users in other channels, the bot must create and send the URL.
Video call URL is used when a video call ticket is created, and the user interface (UI) is not controlled by Yellow.ai in certain channels, excluding the widget.
This article will guide you through the process of shortening and configuring video call URLs.
## Steps to configure video call URL
To configure video call URL, follow these steps:
1. When a ticket is created for video call, an event is triggered.
2. Handle the triggered event and call the below function (this returns the long-form URL):
```
https://app.yellow.ai/api/agents/settings/getVideoCallUrlForTicket?bot=x1553936559750&ticketId=103987&baseRegionUrl=https://app.yellow.ai
```
3. Pass the long-form URL to a URL shortening API.
4. Send out the shortened URL to the intended participants.
By integrating a URL shortening API into the process, the Video Call URL is easily shareable and accessible, regardless of the communication channel.
---
## Fetch CSAT(bot & agent feedback) from bot users on data explorer
To collect user/customer feedback on yellow.ai, you can take the below approaches:
1. **Collect user feedback for the bot interaction** (on web widget): This is done by creating a flow using Feedback node. When this node is reached during the flow, feedback questions will be posed to the users.
2. **Collect user feedback for bot/agent interaction via. custom flows** (recommended for other channels like Facebook, WhatsApp, etc.): Create a custom flow on Automation.
This data will be available in the [Data Explorer](https://docs.yellow.ai/docs/platform_concepts/growth/dataexplorer/intro) section.
You can visualize it further by taking advantage of [Dashboards](https://docs.yellow.ai/docs/platform_concepts/growth/Dashboards/dashboardintro) and [Visualisation](https://docs.yellow.ai/docs/platform_concepts/growth/visualisation/visualization).
-----
## 1. Default user feedback for bot interaction
1. In **Automation**, at the end of your existing flow, add a [feedback node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#27-feedback) to collect user feedback on the **bot-customer** and **inbox agent-customer** conversation.
-------
## 2. Default user feedback for agent interaction
1. Create a flow using the [Raise ticket](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/raise-ticket) action node.
2. Configure Inbox agents .
3. Enable **CSAT** from the inbox settings.
4. After a chat ticket is closed, your customers will be asked for feedback on the agent interaction.
> Click [here](https://docs.yellow.ai/docs/platform_concepts/inbox/inbox-settings/workflows/csat) to know more about Agent CSAT score.
----
## 3. Customize user feedback flow on Automation
> The above-mentioned default feedback methods will work only on your **website chatbot**.
You can create flows in Automation to manually collect user feedback (from the bot interaction) for two use cases:
1. Collect CSAT feedback for other channels like WhatsApp, Facebook, etc. after an inbox live agent interaction.
2. Customize your feedback parameters. The feedback node collects only the rating and comments from the user. If you want to collect other details, like "which product would you likely recommend to your friends," you can use this method.
Follow the given steps:
1. Create a feedback flow.
- You can add [prompt nodes](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes) to ask questions or other details and store the response in a variable.
- To collect ratings, use a node to present options ranging from 1 to 5 (the CSAT score) and **store the response** in a variable (for example, feedback).If your channel is WhatsApp, you can use the [WhatsApp list node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#22-whatsapp-list). You can also use [Quick replies node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#14-quick-replies) to fetch the user rating.
2. Create a database with the required columns (for instructions, see [here](https://docs.yellow.ai/docs/platform_concepts/studio/database)).
3. Send the collected data (feedback variables) into the database using the [database action node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/database-node) in the bot flow.
4. Connect this feedback flow at the end of your use case (i.e., the other flow where the bot interaction is expected to end) using an [Execute Flow node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/execute-flow) or when the [ticket is closed](https://docs.yellow.ai/docs/cookbooks/inbox/ticketclose-message).
-----
## 4. View user feedback on Insights
1. **Data from feedback node for bot interaction**:
Available on **Insights** > **Data explorer** > **Default tables** > **User feedback**.
2. **Data from CSAT settings for agent interaction**:
Available on **Insights** > [Data Explorer](https://docs.yellow.ai/docs/platform_concepts/growth/dataexplorer/defaulttables) > **Chat tickets** table .
> Chat tickets and User feedback are default database table, you need not create any new table to save this data.
4. **Data from custom flows for bot/agent interaction**:
Available on **Insights** > **Data Explorer** > **Custom Tables** > Select the table in which you have stored the feedback.
You can save these tables(queries) and view them on a separate dashboard. Refresh the page to update dashboards with newly added data points.
---
## Bot performance metrics for indept insights on Flows
The **Bot Performance Metrics** dashboard provides detailed insights into the effectiveness and usage of your bot. To access this dashboard, navigate to **Dashboard > Bot Performance Metrics**. All data in this dashboard can be filtered for specific **dates** or **time ranges** to provide tailored analytics.
This guide explains the various metrics available in the dashboard, how to interpret them, and when to use them to optimize your bot's performance.
---
## Bot performance metrics KPIs
Following are the Bot Performance Metrics Key performance indicators(KPIs):
### 1. Flow Visits
Tracks the number of times users enter a specific flow within the bot. This metric helps measure the popularity and usage of different bot flows.
**Data Details:**
- **Data Source:** Number of visits completed through flows.
- **Table:** User Engagement Events.
- **Filter:** Event is "journey-completed."
- **Summarize By:** Sum of count.
- **Group By:** Journey.
**When to Use:**
- To understand which flows are most frequently accessed.
- To identify less-used flows that may require improvements or better promotion.
---
### 2. Bot Accuracy
Measures the bot's ability to accurately understand and respond to user queries. High accuracy indicates effective natural language processing (NLP) and a well-trained bot.
**Data Details:**
- **Data Source:** Accuracy of bot identification in messages.
- **Table:** Message Events.
- **Filter:** IDENTIFICATIONSTATUS not empty.
- **Summarize By:** Count.
- **Group By:** IdentificationStatus.
- **Visualization:** Pivot.
- **Custom Formula:** `Identified / (Identified + Unidentified)`.
**When to Use:**
- To evaluate the quality of the bot's NLP.
- To identify areas where training data or intents need refinement.
---
### 3. Bot Feedback
Collects user feedback on their interactions with the bot, providing insights into user satisfaction and areas for improvement.
**Data Details:**
- **Data Source:** Feedback provided for bot performance.
- **Table:** User Feedback Table.
- **Summarize By:** Average on rating.
**When to Use:**
- To gauge user satisfaction and identify trends in user sentiment.
- To prioritize improvements based on feedback ratings.
---
### 4. Flow Completion Rate
Calculates the percentage of users who successfully complete a flow from start to finish. Indicates how effectively the bot guides users through processes.
**Data Details:**
- **Data Source:** Completion rate of initiated journeys.
- **Table:** User Engagement Events.
- **Filter:** Event is "journey-started" and "journey-completed."
- **Summarize By:** Sum of count.
- **Group By:** Event.
- **Visualization:** Pivot.
- **Custom Formula:** `(journey-completed / journey-started) * 100`.
**When to Use:**
- To assess the usability and clarity of specific flows.
- To identify points where users abandon flows and improve them.
#### Flow Completion Rate for Each flow
This displays the flow completion rate for each flow.
---
### 5. Deflection Rate
Measures the percentage of user inquiries resolved by the bot without escalation to a human agent. A higher deflection rate indicates effective issue resolution by the bot.
**Data Details:**
- **Data Source:** Deflection rate in user-agent sessions.
- **Table:** User Engagement Events.
- **Filter:** Event is "user-session" and "agent-session."
- **Summarize By:** Count.
- **Group By:** Event.
- **Visualization:** Pivot.
- **Custom Formula:** `(User-Agent / User) * 100`.
**When to Use:**
- To monitor the bot's success in reducing workload for human agents.
- To identify areas where bot responses can be improved for higher deflection.
---
### 6. Utterance Status Split
Categorizes user utterances based on their status (e.g., recognized, unrecognized, ambiguous). Helps in understanding how well the bot processes user inputs.
**Data Details:**
- **Data Source:** Number of messages with an "unidentified" status.
- **Table:** Message Events.
- **Filter:** IdentificationStatus is "unidentified."
**When to Use:**
- To identify intents that are not recognized or are ambiguous.
- To refine training data and improve recognition rates.
---
### 7. API Usage by Status Code
Tracks the status codes returned by API requests made by the bot. Provides insights into the performance and reliability of APIs.
**Data Details:**
- **Data Source:** Usage of API services categorized by status.
- **Table:** API Events.
- **Filter:** API name.
- **Summarize By:** Sum of count.
- **Group By:** Status code.
**When to Use:**
- To monitor API reliability and identify potential issues with integrations.
- To troubleshoot failed API requests based on status codes.
---
### 8. API Requests by Day
Displays the number of API requests made by the bot daily. Useful for tracking bot activity levels and identifying trends or spikes in API usage.
**Data Details:**
- **Data Source:** Usage of API services categorized by status.
- **Table:** API Events.
- **Filter:** API name.
- **Summarize By:** Sum of count.
- **Group By:** Day.
**When to Use:**
- To track daily API activity and identify usage patterns.
- To ensure API request volumes align with expected bot activity.
---
## Understand and analyse issues in a conversation
This guide highlights the information that cna be obtained from the **Conversational issues widget** available on the **Insights > Overview** page.
- On this tab you can find analytics based on the [conversation logs](https://docs.yellow.ai/docs/platform_concepts/analyze/chat-logs) (Automation).
- At the end of the widget, you can analyze the metrics for the selected date range. To see these conversations, click **View conversation logs**, you will be directed to the **Automation > Conversation logs** page.
> 
- There are 2 tabs that can help you analyse the conversation issues, **Overview** and **Analyse**.
------
## 1. Overview of conversational issues
This is a time-series view of the priority issues identified in your bot-user conversations.
| High-level metrics tracked on overview tab|
| ---- |
| **Messages with issues**: This represents the percentage of messages where the below listed issues have been identified out of the total messages exchanged between the user and bot. |
|**Users affected**: This is the percentage of total users that faced one or more of the issues while conversing with the bot. |
| The conversation issues identified on the overview tab |
| --- |
| **Missing bot response**: When an expected bot response does not go through due to a broken flow or a fallback not being configured. |
| **Unidentified**: When the bot is unable to recognize the intent of a user message. |
| **Validator limit exceeded**: When the validation of a particular user message fails more than 3 times consecutively. |
| **Fallback limit exceeded**: When the fallback journey is called more than two times in a row due to the bot not understanding user intent. |
----------
## 2. Analyse and resolve conversational issues
Select the **Analyse** tab to see a detailed view of conversation issues along with their severity and count of total occurrences.
Four common issues encountered by the bot are listed along with the **Suggested next steps**. They are:
1. **Unidentified user response**
2. **Missing bot response**
3. **Validation limit exceeded**
4. **Fallback limit exceeded**
You can click on each issue to get redirected to the conversation logs where those issues have been identified. These conversations are filtered for the selected parameters, that is, applied date range and tag (identified issue).
------
### Steps to identify and fix conversation issues
> Consider the following example to fix the **Missing bot response** issue.
**Missing bot response** can be rectified by opening the conversations, finding the point where the bot response was missing, and configuring a fallback or adding a message to the node, if empty.
1. Click **Missing bot response**. You will be directed to the conversation log page that consists of the conversations that encountered missing bot responses.
2. Open any conversation. Select the **Missing bot response** to identify the exact point.
3. Hover over the text, click on the menu options, and select **Go to node**.
4. You will be directed to the respective flow, modify the flow by adding a fallback/new message as per your use case.
---
## Export reports for a timeframe longer than 190 days
Under **Insights > Data Explorer**, you can view or export notification reports(or other reports) for only the past 190 days. To generate annual or longer-duration reports, use the **Insights > Data export** section.
For more details about Data export, refer to the [documentation here](https://docs.yellow.ai/docs/platform_concepts/growth/dataops).
## Steps to export data older than 190 days
### 1. Access Data export
Navigate to **Insights > Data export**, then click **+ Create Export Rule**.
### 2. Configure Export Rule
- Provide a name for the export.
- Select **Notification Reports** from the data list.
- Choose the export format (JSON or CSV).
- Click **Next**.
### 3. Set Export Frequency
- For historical data, choose **One-time Export**.
- Click **Next**.
### 4. Define Date Range
- Select the desired date range in the dropdown menu.
- A confirmation message will display the selected period (e.g., "You’ll receive data between ___ to ___").
- Verify the range and click **Next**.
### 5. Choose Export Destination
- Select your preferred destination: **Amazon S3**, **Azure Blob**, **Google Cloud Storage**, or **SFTP Server**.
- Follow the prompts to connect your destination.
- Click **Next**.
### 6. Create the Export Rule
- Review the configuration and click **Create Export Rule**.
### 7. Monitor Export Logs
- After creating the rule, click on the rule name to view logs, including:
- Export date and frequency.
- Status of export (Scheduled, Ongoing, Success, or Failure).
- Size of exported data.
- For detailed insights, click on **Job IDs** to access:
- Data source and type (JSON/CSV).
- Size of data.
- Export status (Success or Failure).
- Error details (if the export failed).
:::info
**Export Other Data Types**
The above procedure can be followed for other available data types in **Data export**.
:::
---
## Descriptions of default table columns on data explorer
## API events
| Field | Description |
|--------------|---------------|
| TIMESTAMP | The TIMESTAMP field represents time intervals in 1-minute slots within a 24-hour day. When an event occurs, its timestamp is rounded to the nearest 1-minute interval. The first occurrence creates a new row with the timestamp, and if the same event occurs again within the same 1-minute slot, the count column value for that timestamp is incremented by 1. This allows tracking the number of occurrences of the same event within each 1-minute interval. Subsequent occurrences in the same interval contribute to the count column value. For example: Suppose an event occurs at 9:46:24, its timestamp would be 9:46, creating a new row. If the same event happens at 9:46:37, the count becomes 2 for the 9:46 timestamp. Another event at 10:13:47 creates a new row with a timestamp of 10:13. The count column tracks repeated occurrences within the same 1-minute slot. |
| BID | Business Identifier |
| CUSTOMID1 | Custom Identifier from CDP (Customer Data Platform) |
| CUSTOMID2 | Custom Identifier from CDP (Customer Data Platform) |
| EVENTINFO | Additional Information Stored By Platform (Not for customer customization) |
| IP | User's IP address identified by the platform |
| NAME | Not Applicable (NA) |
| SOURCE | Additional Information Stored By Platform (Not for customer customization) |
| STATUSCODE | Various Status of the API response. 200 Means Success, 404 means Server-side Failure |
| UID | Unique Identifier of User |
| LANGUAGE | Language identified by our platform for the ongoing interaction |
| RESPONSE_TIME| Time taken (in milliseconds) by the server to respond back to the API request |
| COUNT | Number of API Hits |
-----
## Bot events
| Events | Description |
| -------- | -------- |
|bot_loads | Fired when a gets bot loaded on the platform |
|datastore-bulk-upsert|Fired when Bulk insert or update operation is performed on the datastore|
|datastore-delete| Fired when a delete operation is performed on the datastore |
|datastore-failed-delete|Fired when a delete operation fails on the datastore|
|datastore-failed-dropdata| Fired when a drop data action fails on the datastore |
|datastore-failed-find|Fired when a find request is received on the datastore and the request fails|
|datastore-failed-insert|Fired when an insert operation is performed and it fails to insert into the datastore|
|datastore-failed-search|Fired when a search operation is performed on the datastore and it fails|
|datastore-failed-searchDocuments| Fired when a step of the journey is expected or a prompt is shown to the user|
|datastore-failed-update|Fired when the update operation is performed on the datastore and it fails|
|datastore-feedback| Fired when feedback is pushed into the datastore|
|datastore-find|Fired when a find operation is performed on the datastore|
|datastore-insert|Fired when an insert operation is performed on the datastore|
|datastore-search|Fired when a search operation is performed on the datastore|
|datastore-searchDocuments| Fired when a document search operation is performed on the datastore |
|datastore-update|Fired when an update operation is performed on the datastore|
|db_node_fallback|Fired when a notification is received to the mobile widget|
|email-sent|Fired when an email is sent|
|function-execution-time| Fired when a session is created based on a USER message|
|invocation|Fired when a new session is created from a user message for the WhatsApp channel|
|otp-sent|Fired when an OTP is sent|
|otp-verified|Fired when an OTP is verified|
|pdf-convert-api|Fired when a PDF convert API is being hit|
|redis-del |Fired when the delete operation is performed on the Redis memory|
|redis-get|Fired when data is fetched from the Redis memory|
|redis-set |Fired when write operation is performed on the Redis memory|
|synonyms|Fired when a synonym is detected|
|unknown-message |Fired when an unknown message is received|
|widget_loaded|Fired when a widget is loaded|
> Click [here](https://docs.yellow.ai/docs/platform_concepts/studio/events/event-hub#2-type-of-events) to learn about events.
-----
## Chat tickets
| Field | Description |
|-------------------------------------------|---------------|
| USER_ID | Unique identifier for the user in the given channel. |
| RECENT_USER_MESSAGE_TIME | Time of the last user message; null if not responded. |
| CONTACT_PHONE | Phone number of the user collected from the bot. |
| CONTACT_EMAIL | Email of the user collected from the bot. |
| CONTACT_NAME | Name of the user collected from the bot. |
| TICKET_PRIORITY | Priority of the ticket (default: medium). |
| TICKET_CREATION_TIME | Time the ticket is created. |
| SOURCE_CHANNEL | Channel through which the user accessed the bot. |
| TICKET_TRANSFERS | List of ticket reassignments to agents or groups. |
| TICKET_TYPE | Type of the ticket (default: live chat). |
| VOICE_CALL_FLAG | Indicates if video calling is enabled for this ticket. |
| AUTO_TRANSLATE_FLAG | Indicates if auto-translate is enabled for this ticket. |
| RECENT_AGENT_MESSAGE_TIME | Time of the last agent message. |
| ADMIN_ASSIGNMENT_FLAG | Indicates if an admin assigned this ticket to the agent. |
| REPLY_COUNT | Number of aggregate responses given by the agent to the end user. |
| USER_REPLY_COUNT | Number of aggregate responses given by the user to the agent. |
| TICKET_ID | Auto-generated reference number for each incoming ticket. |
| TAGS | Categorization of tickets done with configured words/phrases in inbox settings. |
| COMMENTS | Additional information about the chat ticket, including inactivity, auto-translate, etc. |
| OPEN_TIME | Time the ticket was opened. |
| ASSIGNMENT_TIME | Time the ticket was assigned. |
| RESOLUTION_TIME | Time the ticket was resolved. |
| GROUP_CODE | Category/group to which the ticket was assigned. |
| AGENT_NAME | Name of the assigned agent. |
| AGENT_EMAIL | Email of the assigned agent. |
| REOPENED_AGENT_EMAIL | Email of the agent who reopened the ticket. |
| RESOLUTION_DURATION_CREATE_IN_SECONDS | Duration between resolution time and creation time (in seconds). |
| RESOLUTION_DURATION_ASSIGNED_IN_SECONDS | Duration between resolution time and assigned time (in seconds). |
| QUEUE_WAIT_DURATION_IN_SECONDS | Duration between assigned time and ticket creation time (in seconds). |
| FIRST_RESPONSE_DURATION_IN_SECONDS | Duration between First Response Time (FRT) and assigned time (in seconds). |
| FIRST_RESPONSE_TIME_CREATION_IN_SECONDS | Duration between FRT and ticket creation time (in seconds). |
| ORIGINAL_ASSIGNMENT_TIME | Time the ticket was **first** assigned to an agent. On reassigned tickets this stays the original (first) assignment time; on non-reassigned tickets it matches ASSIGNMENT_TIME. This is the timestamp used to compute FRT. |
| ORIGINAL_FIRST_RESPONSE_TIME | Time of the **first** agent's first response. On reassigned tickets this stays the original first response; on non-reassigned tickets it matches FIRST_RESPONSE_TIME. FRT can be validated as: `(ORIGINAL_FIRST_RESPONSE_TIME − ORIGINAL_ASSIGNMENT_TIME)` = FIRST_RESPONSE_DURATION_IN_SECONDS. |
| AVERAGE_RESPONSE_TIME_IN_MILLISECONDS | Average time taken for agents to respond to each customer reply in all tickets (in milliseconds). |
| ABANDON_DURATION | It measures how long a customer waited for an agent before leaving the chat without being attended. ABANDON_DURATION = Time of Abandonment – Time of Chat Initiation
| AVERAGE_RESPONSE_TIME_IN_SECONDS | Average time taken for agents to respond to each customer reply in all tickets (in seconds). |
| CHILD_BOT_ID | Bot ID from which this chat was raised (for unified inbox). |
| CUSTOM FIELDS | Individual custom fields and their values captured from this live chat. |
| TICKET_STATUS | Possible statuses for a chat ticket: Open, Assigned, Missed, Resolved, and Queued. |
### Status description
| Status | Description |
|----------|-----------------------------------------------------------------------------------------------------------------------------------------|
| Open | Set when an incoming live chat has no available agents, either inside or outside working hours, to handle it. |
| Assigned | Set when a chat is assigned to an agent after being created. |
| Missed | Set as the fallback for all incoming chats that cannot be assigned to agents. This may occur if the queue is not enabled, the queue is full, or offline functionality is not enabled. |
| Resolved | Set when agents close a live chat. |
| Queued | Set when agents are busy or away, or if chat concurrency per agent is full. Incoming live chats are directed to queued chats when queues are enabled. |
-----
## Email tickets
| Field | Description |
|----------------------------------------|-------------------------------------------------------------------------------------------------------------------------------|
| AGENT_EMAIL | Email ID of the assigned agent. |
| AGENT_NAME | Name of the assigned agent. |
| AGENT_ASSIGNMENT_COUNT | The current ticket concurrency assigned to the agent at the time of ticket creation. |
| ADMIN_ASSIGNMENT_FLAG | True if the admin manually assigned this ticket to an agent. |
| ASSIGNMENT_TIME | The timestamp at which the ticket was assigned to the agent. |
| AGENT_ID | Unique identifier for the assigned agent. |
| COLLABORATORS | List of collaborators involved in the ticket. |
| CONTACT_FIRST_NAME | First name of the customer who created this ticket. |
| CONTACT_EMAIL | Email of the customer who created this ticket. |
| TICKET_CREATION_TIME | The timestamp when the ticket was created within the platform. |
| CUSTOM FIELDS | All individual custom fields and their values captured from this email ticket. |
| TICKET_DUE_DATE | Due date of the ticket. |
| FIRST_RESPONSE_TIME | The timestamp of the first response provided by the agent in that ticket. |
| FIRST_RESPONSE_DUE_TIME | Due time for the first response SLA. |
| FIRST_RESPONSE_DURATION_ASSIGNED_IN_SECONDS | Total time duration between the ticket being assigned to an agent and the agent providing the first response. |
| FIRST_RESPONSE_DURATION_CREATE_IN_SECONDS | Total time duration between the ticket being created in the platform and the agent providing the first response. |
| FIRST_RESPONSE_TARGET | The target timestamp by which the first response must be provided according to the SLA policy. |
| GROUP_CODE | The group to which the ticket is assigned. |
| RECENT_AGENT_MESSAGE_TIME | The timestamp of the last agent message in that ticket. |
| RECENT_BOT_MESSAGE_TIME | The timestamp of the last bot message in that ticket. |
| RECENT_REOPEN_TIME | The last timestamp when the ticket was reopened. |
| RECENT_USER_MESSAGE_TIME | The timestamp of the last user message in that ticket. |
| MANUAL_ASSIGNMENT_FLAG | True if the ticket was manually assigned to an agent. |
| PARENT_FLAG | True if other tickets are merged into this ticket (parent). |
| PARENT_TICKET_ID | Ticket ID of the parent ticket to which this ticket is merged. |
| TICKET_PRIORITY | The priority of the ticket, set during its creation or changed by the agent (High, Medium, or Low). |
| REOPENED_FLAG | True if the ticket is reopened. |
| REOPENED_AGENT_EMAIL | Email ID of the agent to whom the ticket was reopened. |
| REOPENED_BY | The agents name who reopened the ticket. |
| REOPEN_COUNT | Count of times the ticket is reopened. |
| REPLY_COUNT | Count of exchanges between the customer and the agent. |
| RESOLUTION_DUE_TIME | Due time for ticket resolution. |
| RESOLUTION_DURATION_ASSIGNED_IN_SECONDS| Total time duration between the ticket being assigned to an agent and the ticket getting resolved. |
| RESOLUTION_DURATION_CREATE_IN_SECONDS | Total time duration between the ticket being created in the platform and the ticket getting resolved. |
| RESOLUTION_TARGET | Whether the resolution SLA was achieved or breached. |
| RESOLUTION_TIME | The timestamp when the ticket was marked resolved by the agent. |
| RESPONDED_FLAG | Indicates whether the agent has responded to the ticket. |
| TICKET_STATUS | Status of the email ticket (Opened, In-progress, On-hold, Resolved, or Pending). |
| TICKET_SUBJECT | The subject mentioned in the email ticket. |
| TAG_NAME | All the tags applied to this particular ticket. |
| TICKET_ID | Auto-generated reference number for each incoming ticket. |
| TRANSFERRED_FLAG | True if the ticket has been transferred at least once. |
| USER_ID | Unique identifier for the user in the given channel. |
| USER_REPLY_COUNT | Number of times the user has replied in the ticket. |
-----
## Inbox call records
| Field | Description |
|---------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------|
| BOT_ID | Bot ID associated with the configured inbox for handling calls. |
| USER_ID | Unique identifier for the user in the given channel. |
| TICKET_ID | Auto-generated reference number for each incoming ticket related to the voice call. |
| CALL_DURATION | Duration between the call pickup time and call end time. |
| CALL_SID | Unique identifier for the voice call. |
| CALL_PICKUP_TIME | Time at which the call is picked up by the agent. |
| CALL_END_TIME | Time at which the call is ended, either by the agent, user, or due to an error. |
| CALL_WRAPUP_TIME | Time at which the ticket status transitions to wrap-up after the call ends. |
| CALL_WRAPUP_DURATION | Duration between the ticket resolved time and ticket wrap-up time. |
| CALL_RECORDING_URL | URL link to the call recording (audio) between the agent and the customer. |
| CALL_QUEUE_START_TIME | Queued time of the ticket or call. |
| CALL_QUEUE_WAIT_TIME | Duration between the first time the ticket is queued and the pickup time. |
| CALL_ASSIGNED_TIME | Time at which the ticket is assigned to an agent. |
| CALL_CSAT_AGENT_SCORE | The default Customer Satisfaction (CSAT) feedback received for the agent after the voice call. |
| CALL_CSAT_TICKET_SCORE | The default CSAT feedback received for the overall ticket after the voice call. |
| TIMESTAMP | Created time of this voice call on the inbox. |
| QUEUE_DROP_OFF_TYPE | Indicates whether the user dropped off from the queue and the reason for the drop-off. |
| QUEUE_DROP_OFF_TIME | Time at which the user dropped off from the queue. |
| REQUEUE_COUNT | Number of times the call or ticket was requeued. |
| DISCONNECTED_BY | Indicates which peer (agent or user) hung up the call. |
----
## Inbox events
| Field | Description |
|------------|--------------------------------------------------------------|
| TIMESTAMP | The date and time when the event was triggered. |
| AGENTID | Unique Identifier (UID) for agents, used for internal purposes.|
| BID | Business Identifier - a distinctive identifier for the business involved.|
| CATEGORY | The name or code of the group to which the raised Inbox ticket belongs.|
| SOURCE | The communication channel through which the user is engaging with the bot (e.g., Whatsapp, Facebook, Yellow Messenger).|
| UID | User Identifier - a unique identifier assigned to each user for tracking and distinction.|
| EVENT | Indicates the status of the event, such as assigned, missed, open, queued, reassigned, resolved, or answered.|
### Events description
| Event Name | Description |
|--------------|-------------------------------------------------------------------------------------------------------------|
| assigned | Triggered when a chat is assigned to an agent for resolution. |
| missed | Triggered when a chat transitions into the "Missed" status. |
| open | Triggered when a chat enters the "Open" status due to the absence of available agents. |
| queued | Triggered when a chat is placed in a queue, typically due to agent unavailability or full chat concurrency. |
| reassigned | Triggered when a chat is reassigned from one agent to another. |
| resolved | Triggered when an agent clicks "Resolve" to mark the chat as resolved or the chat is auto-closed. |
| answered | Triggered when the agent has responded to the ticket at least once. |
-----
## Knowledge base report
| Field | Description |
|-------------------|---------------------------------------------------------------|
| TIMESTAMP | Time at which the query was made to the Language Model (LLM) |
| ORIGINAL_QUERY | Message typed out by the user (Input) |
| CONV_HISTORY | Previous user and bot messages before the user's message |
| REPHRASED_QUERY | True query considering context from conversational history |
| DOCUMENT_TAGS | Document tag values, if any, passed |
| WAS_SUMMARY_GIVEN | True or false value stating if the response was summarized |
| ANSWER | Copy of the answer provided by the bot to the asked query |
| LINKS | Copy of the web links provided by the bot |
| SITE_KEY | Website domain based on which the answer was retrieved |
| UID | Unique user ID of the user having the conversation |
| TRACE_ID | Unique ID of the query for further analysis on search |
-----
## Knowledge base articles
| Field | Description |
|-----------------|-----------------------------------------------------------------------------------------------------------------|
| ARTICLE_ID | Identity number assigned to the article during its creation. |
| ARTICLE_TITLE | Title of the published article. |
| VISIBILITY | Visibility status selected during article creation, either Internal or External. |
| SUBCATEGORY | The immediate folder or subcategory under which the article is organized. |
| PARENT_CATEGORY | The name of the top-level category under which the article is classified. |
| VIEWS | The number of views received by this particular article. |
| LIKES | The number of likes received on this particular article. |
| DISLIKES | The number of dislikes received on this particular article. |
| LANGUAGE | The language selected during article creation; the article is visible on the website in this specified language. |
| PUBLISHED_AT | The timestamp indicating when the article was published. |
------
## Message events
| Field | Description |
|----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| TIMESTAMP | The TIMESTAMP field represents time intervals in 1-minute slots within a 24-hour day. When an event occurs, its timestamp is rounded to the nearest 1-minute interval. The first occurrence creates a new row with the timestamp, and if the same event occurs again within the same 1-minute slot, the count column value for that timestamp is incremented by 1. This allows tracking the number of occurrences of the same event within each 1-minute interval. Subsequent occurrences in the same interval contribute to the count column value. For example: Suppose an event occurs at 9:46:24, its timestamp would be 9:46, creating a new row. If the same event happens at 9:46:37, the count becomes 2 for the 9:46 timestamp. Another event at 10:13:47 creates a new row with a timestamp of 10:13. The count column tracks repeated occurrences within the same 1-minute slot. Ex: 00:00:00 UTC. |
| CITY | User's city retrieved from the IP address. String data type. |
| COUNTRY | User's country retrieved from the IP address. String data type. |
| DEVICE | User's device type, such as Desktop, Tablet, or Mobile. String data type. |
| IP | User's IP address. Integer data type. |
| MESSAGETYPE | Type of the message sender, e.g., BOT, USER, AGENT, NOTIFICATION. |
| PLATFORM | User's device operating system, e.g., Windows, Linux, etc. String data type. |
| REGION | User's state retrieved from the IP address. String value. |
| SOURCE | Channel in which the user is chatting with the bot. Example: Whatsapp, Facebook, yellowmessenger. |
| UID | Unique Identifier of the User. |
| SESSIONID | Unique Identifier per session. |
| SESSION_SUM | Seconds since the last message. The time is stored in seconds from the previous User/Bot/Agent message. |
| CUSTOMID1 | Custom Identifier from Customer Data Platform (CDP). |
| CUSTOMID2 | Custom Identifier from Customer Data Platform (CDP). |
| UTM_CAMPAIGN | Associated with the campaign's name from the Engage module. |
| UTM_MEDIUM | Associated with the campaign's medium from the Engage module. |
| UTM_SOURCE | Associated with the campaign's source from the Engage module. |
| LANGUAGE | Language identified by our platform during the ongoing interaction. |
| BID | Business Identifier. |
| INTERACTIONTYPE | User input classification, e.g., user chose a quick reply or typed the input. |
| COUNT | Rolled-up value of that event where data was exactly the same, just a difference in time. Associated with timestamp description. |
| identificationStatus | Denotes if a user message was identified/unidentified. |
| lastMessageType | Denotes if the last message in the chat was from the Bot/User/Agent. |
------
## Notifications report
| Field | Description |
|-------------|--------------------------------------------------------------------------------|
| NAME | Name of the campaign |
| CAMPAIGNID | Unique ID assigned to the campaign. |
| REPORTID | Unique ID assigned to the campaign report. |
| SENDERID | Alphanumeric or numeric string that identifies the sender of a message |
| USERID | Unique ID for each User present in the User360 Table |
| CDPUSERID | Unique ID of the user (in User360) to whom the campaign was sent |
| TEMPLATEID | Unique ID of the template used in the campaign |
| MESSAGEID | Unique ID assigned to the message within the campaign sent to the user. |
| STATUS | |
| SOURCE | Channel through which the campaign message was sent. Example: Whatsapp, Facebook, yellowmessenger |
| SMSUNITS | The number of SMS units consumed for a single message in the campaign. |
| SCHEDULEDAT | Date and time when the campaign was scheduled to send. |
| SENTAT | Date and time when the campaign was sent |
| DELIVEREDAT | Date and time when the campaign was successfully delivered. |
| READAT | Date and time when the recipient read the campaign message |
| REPLIEDAT | Date and time when the recipient replied to the campaign |
| REPLY | Content of the reply received from the recipient |
| ERRORMESSAGE| Any error message generated during the campaign delivery process. |
-------
## User engagement events
Following are the fields tracked on the user engagement events table:
| Field | Description |
|------------------|----------------------------------------------------------------------------------------------------------------------|
| TIMESTAMP | The TIMESTAMP field represents time intervals in 30-minute slots within a 24-hour day. When an event occurs, its timestamp is rounded to the nearest 30-minute interval. The first occurrence creates a new row with the timestamp, and if the same event occurs again within the same 30-minute slot, the count column value for that timestamp is incremented by 1. This allows tracking the number of occurrences of the same event within each 30-minute interval. Subsequent occurrences in the same interval contribute to the count column value. For example: Suppose an event occurs at 9:46, its timestamp would be 9:30, creating a new row. If the same event happens at 9:59, the count becomes 2 for the 9:30 timestamp. Another event at 10:13 creates a new row with a timestamp of 10:00. The count column tracks repeated occurrences within the same 30-minute slot. |
| BID | Business Identifier, a unique identifier for the business associated with the event. |
| CATEGORY | An umbrella term for journeys; certain journeys can be grouped under this category. |
| CITY | Approximate city location identified by the platform. |
| COUNTRY | Approximate country location identified by the platform. |
| CUSTOMID1 | Custom Identifier from Customer Data Platform (CDP). |
| CUSTOMID2 | Custom Identifier from Customer Data Platform (CDP). |
| DEVICE | Approximate user device value identified by the platform, such as mobile or desktop. |
| EVENT | The specific event that occurred. |
| EVENTINFO | Additional information stored by the platform (not for customer customization). |
| JOURNEY | The flow name under which this event was generated. |
| PLATFORM | Approximate underlying platform of the user device (e.g., Desktop can have Windows, Linux). |
| STEP | Step name in the Automation flow under which this event was generated. |
| REGION | Geographical location (state) identified where the bot is being used. |
| SOURCE | Different channel integration from where the user triggered the event, such as Yellowmessenger, WhatsApp, etc. |
| TARGETINFO | Used for storing additional information for some events, such as journey switched. |
| UID | Unique Identifier of the User. |
| SESSIONID | Unique Identifier of the User for a 24-hour timeframe from the first event triggered by the user. |
| LANGUAGE | Language identified by the platform during the ongoing interaction. |
| INTERACTIONTYPE | User input classification, for example, whether the user chose a quick reply or typed the input. |
| COUNT | Rolled-up value of the event where the data was exactly the same, with differences only in time (this is associated with the timestamp description). |
| VALUE | The VALUE field is used for pushing a numerical value associated with an event. By default, if no specific value is provided, it is set to 0. This field allows you to convey a quantitative aspect related to the event, providing additional context or information. |
### Events description
Following are the events tracked on the user engagement events table:
| Event | Description |
|-------------------------|---------------------------------------------------------------------------------------------------------------------|
| agent-session | Fired when a live agent actively participates in a conversation. An agent session starts when the agent sends the first response to a ticket and continues for 24 hours from that point. Any additional tickets created during this 24-hour window are counted as part of the same agent session. If a ticket is closed without any agent response, no agent session is created. Therefore, the number of agent sessions will always be less than or equal to the number of tickets created. |
| agent-transfer | Fired when a chat conversation is transferred to a live agent |
| banner-cta-clicked | Fired when the User clicks on the link configured in the callout banner |
| bot-closed | Fired when the Bot is closed by the user (close button) |
| bot-icon-clicked | Fired when the Bot avatar (in title bar) is clicked by the user |
| bot-icon-loaded | Fired when the Bot avatar is displayed to the user (on load) |
| bot-loaded | Fired when the Bot script is loaded on the website |
| bot-opened | This occurs when a user clicks on the chat bubble to open the bot. |
| bot-session | Fired when a session is created based on a bot message (first message sent by the bot). It has a session time window of 24hrs for a given UID and source |
| business-initiated | Fired when a new session is created by notification from the business side for the WhatsApp channel |
| card-cta-clicked | Fired when the User clicks on the link configured in the card buttons |
| condition-recorded | Fired when a condition node is executed in a flow |
| feedback | Fired when a user gives feedback after completing the chat |
| first-message | Fired when a new profile of a user is created |
| first-message-bid | Fired when a user profile is updated with the bid for the first time |
| home-button-click | Fired when a user clicks on the home button in the chat widget |
| invalid-response | Fired when an invalid response other than the provided option is selected/entered by the user |
| journey-completed | Fired when a journey gets completed for the user |
| journey-started | Fired when a journey starts for the user |
| journey-switched | Fired when a journey is switched by NLP System for the user due to utterance matching another journey |
| message-hyperlink-clicked | Fired when the User clicks on the link configured in the text message |
| new-session | Fired when a new session is created |
| notification-received | Fired when a notification is received on the mobile widget |
| optin | Fired when a WhatsApp opt-in is added |
| optout | Fired when a WhatsApp opt-out is added |
| otp-sent | Fired when an OTP sent from the bot using the platform function |
| otp-verified | Fired when an OTP is verified from the bot using the platform function |
| page-loaded | Fired every time the client website page is loaded/reloaded where our script is running |
| pwa-loaded | Fired when the PWA version of the bot script is loaded |
| pwa-opened | Fired when the PWA bot is opened by the user |
| step-expected | Fired when a step of the journey is expected / prompt is shown to the user |
| step-recorded | Fired when input is given by the user for a step (step value is recorded) of a journey |
| unidentified-utterance | Fired when a user message is not understood by the Bot |
| user-initiated | Fired when a new session is created from a user message for the WhatsApp channel (this is only when user messages the business through WhatsApp channel) |
| user-revisited | Fired when the chat widget loads for the user's IP address on subsequent visits. This event is specific to bots hosted on websites. |
| user-session | Fired when a session is created based on a USER message. Value gets incremented only when user sends the first message.|
| user-visited | Fired when the chat widget loads for the user's IP address for the first time. This event is triggered once for the lifetime of the user's unique ID. It is specific to bots hosted on websites |
**Other events**:
- inbound-overlay-closebtn
- inbound-overlay-conversion
- inbound-overlay-impression
- inbound-widget-closebtn
- inbound-widget-conversion
- inbound-widget-impression
---------
## User feedback
| Field | Description | Value Format |
|-------------------|------------------------------------------------------------|--------------------------------------------------|
| BOTID | Bot ID assigned by the platform. | Integer (e.g., x1657623696077) |
| UID | User ID generated by the platform. | Integer (e.g., 1836013421788526118418800767619) |
| SESSIONID | Session ID generated by the platform. | String (e.g., 65a8d2971e1a2100011a2433) |
| SURVEYTYPE | Type of feedback collected in the Feedback card. | String (e.g., Star, Thumbs) |
| NODETYPE | Type of node, indicating PROMPT_FEEDBACK or MESSAGE_FEEDBACK.| String |
| JOURNEYNAME | Journey/Flow name where the feedback card is configured. | String |
| JOURNEYSLUG | Journey slug where the feedback card is configured. | String (e.g., new-feedback-flow_ysdkao) |
| STEPSLUG | Step slug where the feedback card is configured. | String (e.g., ae4c7ac271f37ccd) |
| SOURCE | Channel from which the user has visited (always yellowmessenger). | String |
| RATING | Rating given by the user in the Feedback card (1 to 5). | Integer (e.g., 1, 2, 3, 4, 5) |
| SCALE | Scale in the Feedback card (2 for Thumbs, 5 for Star). | Integer |
| FEEDBACKS | Text feedback given by the user. | String (e.g., ["Quick resolution"]) |
| CUSTOMTAG | Placeholder for custom tags (Not Applicable). | Not Applicable |
| RESPONSE | Feedback quality given by the user (Positive: 3/4/5 in star, Negative: 1/2 in star). | String |
| CREATEDAT | Feedback submission date & time. | Date (e.g., Thu Jan 18 2024 12:56 PM) |
| LASTBOTMESSAGE | Last message sent by the bot before collecting feedback. | String |
| LASTUSERMESSAGE | Last message sent by the user before collecting feedback. | String |
-----
## Video chats
| Field | Description |
|---------------------------|-------------------------------------------------------------------------------------------------------------------------------|
| TICKET_ID | Auto-generated reference number assigned to each incoming ticket. |
| CHILD_BOT_ID | Bot ID of the child bot if orchestrator parent bot and unified inbox are enabled. |
| AGENT_NAME | Name of the Inbox Support Agent handling the ticket (e.g., Amudhan S). |
| AGENT_USERNAME | Email of the Inbox Support Agent without special characters (e.g., amudhanyellowai). |
| CLIENT_EMAIL | Customer's email ID if provided. |
| CLIENT_NAME | Customer's name if provided. |
| CALL_DURATION_IN_SECONDS | Duration of the video call in seconds (difference between start and end time). |
| START_TIME | Timestamp indicating the start time of the video call. |
| END_TIME | Timestamp indicating the end time of the video call. |
| MEETING_ID | Unique identifier assigned to each meeting. |
| MEETING_NAME | Internal string for meeting identification (e.g., `${ticket.botId}_${ticket.ticketId}_${ticket.assignedTo}_${ticket.uid}`). |
| MEETING_END_REASON | Reason for the completion of the meeting, typically when all the participants leave. |
| DID_AGENT_JOIN | Indicates whether the agent joined the call. |
| DID_CLIENT_JOIN | Indicates whether the user joined the call. |
| WHO_HUNG_UP | Specifies who initiated the call hang-up. |
| RECORDING_ID | Identifier number assigned to each recording. |
| RECORDING_STATUS | Processing status of the recording (e.g., pending, completed). |
## Analytics (Custom table)
Analytics table can be found under custom tables in which the following data is captured.
| Fields | Description |
|--------------------------|---------------------------------------------------------------------------------------------------------------------------|
| CHATURL | Link to Chat Transcript: e.g. https://app.yellow.ai/public/messages/a9c9844ad89bb7aeb6a3918ad57623c37616acfc6c094e3b529ad0a763323f9e687450946280f5eca561274bdc0d6360510eff61eb0b24d55cb5c1e7092c/660a37f54a1f6800016fd072 |
| TIMESTAMP | Date and Time when event was triggered: Sun Mar 31 2024 11:28 PM |
| AEVENT | Event triggered upon an action. This includes both OOB, and custom events configured in the bot: e.g. welcome_message, kb_question_not_answered, booking_done |
| MESSAGEID | Unique ID set in backend for each message: e.g. 123456789 |
| PROFILE_PLATFORM | Platform through which user accessed the chatbot: e.g. Web, SDK |
| PROFILE_BROWSER | Browser through which user accessed the chatbot: e.g. Safari, Chrome, Mozilla |
| PROFILE_CITY | City of user accessed the chatbot (fetched from IP address): e.g. San Francisco, New York City |
| PROFILE_COUNTRY | Country of user that accessed the chatbot (fetched from IP address): e.g. India, Abu Dhabi |
| PROFILE_COUNTRY_CODE | Country code of user that accessed the chatbot (fetched from IP address): e.g. US, CA, IN |
| PROFILE_DEVICE | Type of device from which the user accessed the chatbot: e.g. Mobile, Desktop, Tablet |
| PROFILE_IP | IP address of the user: e.g. 192.168.1.1 |
| PROFILE_LATITUDE | Latitude value of user's location: e.g. 39.73915 |
| PROFILE_LONGITUDE | Longitude value of user's location: e.g. -104.9847 |
| PROFILE_NAME | (User) Profile name set up in backend. This will be random values so that user privacy is maintained: e.g. John Doe, Jane Smith |
| PROFILE_OS | Operating system through which user accessed the chatbot: e.g. Windows 10.0, macOS 10.15.7 |
| PROFILE_PAGEURL | URL of the page from which the user accessed the chatbot. e.g. https://yellow.ai |
| PROFILE_DEVICETYPE | Type of device from which the user accessed the chatbot: e.g. Microsoft Windows, Apple Mac |
| PROFILE_REGION | Region of user that accessed the chatbot (fetched from IP address): e.g. California, Florida |
| PROFILE_SOURCE | Device, OS, and Browser details of the user: e.g. Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36 |
| PROFILE_TIMEZONE | Timezone of user's location: e.g. -04:00, +05:30 |
| PROFILE_USERAGENT_BROWSER | Browser used by the agent to whom the user is connected to: e.g. Safari, Chrome, Mozilla |
| PROFILE_USERAGENT_DEVICE | Device used by the agent to whom the user is connected to: e.g. Mobile, Desktop, Tablet |
| PROFILE_USERAGENT_OS | OS of the device used by the agent to whom the user is connected to: e.g. Windows 10.0, macOS 10.15.7 |
| PROFILE_USERAGENT_PLATFORM | Platform used by the agent to whom the user is connected to: e.g. Web, SDK |
| PROFILE_USERAGENT_SOURCE | Device, OS, and Browser details of the agent to whom the user is connected to: e.g. Microsoft Windows, Apple macOS |
| PROFILE_WIDGETVERSION | Version of the chat widget accessed by the user: e.g. V1, V2 |
| SOURCE | Channel in which the user is chatting with the bot: e.g. Whatsapp, Facebook, yellowmessenger |
| UID | Unique Identifier of User: e.g. 10182708542979041342360504723 |
| VALUE | |
| MESSAGEID | |
| PROFILE_END_IP | |
| PROFILE_START_IP | |
| PROFILE_TITLE | |
| PROFILE_UTM_CAMPAIGN | |
| PROFILE_UTM_MEDIUM | |
---------------
## Contained resolution analysis
These KPIs are tracked for data generated in the Analyze module (**Analyze > Topics**).
| Fields | Description |
|-------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------|
| Chat URL | URL link of the conversation (transcript) between the user and bot/agent |
| Topic | A conversation topic is the primary subject or query the user seeks assistance or information about |
| Topic Description | Summary of the topic discussed |
| User Query | Summary of the query the user asked the bot or agent |
| Resolution | Summary of the resolution provided by the bot or agent from the conversation |
| Contained | Indicates if the chat was solely handled by the bot or transferred to an agent. If True, the query was handled/contained by the bot. If False, both bot and agent handled the query |
| Analysis Type | This value states whether the conversation that was analyzed was between user & bot, or user & agent |
| Automation | Indicates if the resolution can be added to the bot's knowledge base and if it can be automated. For user-bot conversations, the value is empty. For user-agent conversations, it can be either True or False |
| Automation Reason | Reason provided by the model for marking automation as True or False |
| Resolution Status | Indicates whether the user’s query was successfully addressed by the bot/agent (Possible values: Resolved or Unresolved) |
| Resolution Status Reasoning | Reason provided by the model for generation of resolution status |
| User Sentiment | Overall sentiment of the user (Possible values: Positive/Negative/Neutral) |
| User Sentiment Reasoning | Reason provided by the model for generating user sentiment value|
| User ID | Unique ID for each user |
| Session ID | Session ID generated by the platform for each session |
| Source | Channel where the conversation happened (e.g., WhatsApp, Facebook, yellowmessenger, etc.) |
| Conversation Start Time | Time at which the conversation started |
| Conversation End Time | Time at which the conversation ended |
| Timestamp | The date and time when the report was generated and added to data explorer |
:::note
Use Conversation Start Time & Conversation End Time as the primary reference for when the conversation occurred, as the analysis report is generated after the session ends and may not be on the same day.
:::
-----------
## LLM usage metrics
| **Field** | **Description** | **Value** |
|--------------------|------------------------------------------------------|----------------------|
| TIMESTAMP | Time | Datetime |
| SENDER | Sender ID/UID of the user | String |
| SESSION_ID | Session ID of the user | String |
| TRACE_ID | Trace ID of the message | String |
| SOURCE | Source of the message (YM/WhatsApp/etc.) | String |
| SUCCESS | Whether the API call returned a response or not | Boolean |
| PROVIDER | LLM Service Provider (Open AI, Azure Open AI, etc.) | String |
| MODEL | Name of the model | String |
| RESOURCE | Name of the resource (only in the case of Azure Open AI) | String |
| EXECUTION_TIME | Time taken by the LLM API call | Milliseconds |
| PROMPT_TOKENS | Number of tokens in the input prompt | Number |
| COMPLETION_TOKENS | Number of tokens in the generated response | Number |
| TOTAL_TOKENS | Sum of PROMPT_TOKENS and COMPLETION_TOKENS | Number |
| CUSTOM_LLM_KEY | True if the client is using their own credentials; otherwise False | Boolean |
| WORKFLOW | Workflow ID of the flow where the node is present | String |
| NODE_ID | Node ID of the node | String |
------
## WhatsApp consumption
| **Field** | **Description** |
|---------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| TIMESTAMP | The day the count is calculated |
| WABA_ID | Unique WhatsApp Business Account ID provided by Meta |
| PHONE_NUMBER | WhatsApp business phone number linked to the customer |
| BUSINESS_INITIATED_AUTHENTICATION | Conversations for authenticating users with one-time passcodes, such as account verification, recovery, or integrity challenges |
| BUSINESS_INITIATED_MARKETING | Conversations for marketing purposes like new product announcements, targeted promotions, or cart abandonment reminders |
| BUSINESS_INITIATED_UTILITY | Conversations for follow-ups on user actions or requests, such as order updates, account alerts, or feedback surveys |
| USER_INITIATED_SERVICE | Conversations for resolving customer inquiries |
| CONVERSATION | 24-hour message threads between you and your customers, opened and charged when your messages are delivered |
---------
## Call Details Report (CDR)
If you are using voice bots, you can schedule reports to be sent to your email. This report includes metrics like the number of distinct calls attended by the bot and the total billing duration for the selected timestamp.
Learn about CDR in detail [here](https://docs.yellow.ai/docs/cookbooks/voice-as-channel/reporting/cdr).
-------
:::info
Time is mentioned in milliseconds.
:::
---
## Steps to Fix Data Errors in a database table when new data is uploaded/inserted
Fixing data errors is essential for maintaining the accuracy, reliability, and usability of the information stored in a database table. This is particularly important for performing searches, as data errors can prevent the successful retrieval of new information that is added to the table.
****
## Step 1: Run cURL
Run the below curL on Postman- (Production/ Staging/ Sandbox)
```
curl --location 'https://app.yellow.ai/api/data/data/reIndex?bot=x1611920798285&collection=customer_details' \
--header 'x-auth-token: 8a4f1e914fceb6fe69df01f27da4a9a0594980694d79d52dcf50b60850c91d1a6V77z4YIES88iN-CbDE3j'
```
## Step 2: Add cookie editor extension
Download and add the cookie editor extension to Chrome for running the cookie and generating the x-auth-token (Production/ Staging/ Sandbox).
## Step 3: Generate x-auth-token key
x-api-key isn’t suitable for use here, generate the x-auth-token key.
1. Open cookie-editor extension on the database table for the table you want to **Fix data errors**.
****
2. Select the value under **ym_xid**.
****
3. Paste the value under **Headers** in Postman with key as x-auth-token.
****
## Step 4: Verify database
Open the Database table, refresh the page, and verify whether the *Fix data errors* issue has been resolved in the table.
**Sample response**:
```
{
"success": true,
"message": "re-index",
"data": "done",
"subscriptionExceeded": false
}
```
---
## Knowledgebase Query Debugging
In this document, you will understand how to analyze a specific query in KB report.
Follow these steps:
1. Within the **Insights > Data Explore**, locate the **Knowledge Base Report**. This report contains all the queries and their corresponding outputs.
2. You can filter the queries by `trace-id` or `query` to find the specific query you want to analyze.
3. Click on the query highlighted in blue.
4. A new window will open displaying comprehensive details of the selected query, including:
* **Original Query**: The initial query made by the user.
* **Rephrased Query**: The system rephrases the query based on previous conversations.
* **Previous Conversation**: Context from before the current user message.
* **Summary Answer**: The concise answer generated by the system.
* **Search Results**: Located on the right side, showing the results the system used to generate the answer.
* **Preferred Results**: If a specific result is marked as preferred, it indicates that the answer was generated from that result.
:::info
**Points to remember**:
* **Empty answers**: If the answer field is empty, it means the model was unable to find a suitable answer or was not confident about the correct answer.
* **Rephrased query**: The system generates the rephrased query based on previous conversations to enhance the accuracy of the summary answer.
* **Summary answer**: This is derived from the rephrased query to provide a more precise response.
:::
---
## Native queries to fetch data explorer data/columns
The existing filters in the data explorer only allow filtering rows. By using SQL queries, we can filter and display the desired columns.
Follow these steps to create a SQL query in Data explorer:
1. Open **Data Explorer** > Click **Create Report** > Select **Native Query**.
2. In **Create Report** section, write the queries based on your requirements.
****
Here are some SQL queries you can use:
- To get all the columns from the messages database:
```
SELECT * FROM messages;
```
****
- To get specified columns (date, UID, and session ID):
```
SELECT __time AS CreatedDate, uid AS UID, sessionId AS SessionID FROM messages;
```
****
- To create new columns with static values (e.g., bot ID and bot name):
```
SELECT "x1689236272568" AS BOTID, "Bhavana" AS BOTNAME, uid AS UID FROM messages;
```
****
- To get the count of each user in the database based on the UID:
```
SELECT COUNT(*) AS total_users, uid AS UID FROM messages GROUP BY uid;
```
****
- To get chat details through the messages database:
```
SELECT __time AS CreatedDate, "x1689236272568" AS BOTID, uid AS UID, messageType AS MessageType, sessionId AS SessionID, journey AS Journey, step AS Step FROM messages;
```
****
3. Save the query and create dashboards to filter the data based on the timestamp for further use cases.
****
4. Click **Create Dashboard** > select **New Dashboard**.
****
5. Go to Custom Dashboards to view the newly created dashboard.
****
---
## Schedule downloading of default reports
You cannot schedule or export any default reports as CSV before saving them. To schedule a default table report, follow these steps:
1. Open **Data explorer > Default tables > Report**.
2. Click on any of the default table you want to schedule as a report to your email, click **Summarize**.
3. Remove the Count summarization applied by default by clicking the cross mark, then click **Apply**.
4. Once applied, click **Save query**, give your report a name, and click **Save**.
5. Navigate to **Data explorer > Reports > Custom tab** and open your saved custom query report.
6. Click **Actions** and select either **Schedule report** or **Download as CSV**.
> To schedule a report, refer to the documentation on scheduling reports [here](https://docs.yellow.ai/docs/platform_concepts/growth/dataexplorer/savedreportsactions#1-schedule-a-report).
---
## Standard report scheduling
You can schedule raw reports available on Insights for export as email alerts.
To schedule and download all of your analytics as reports, follow the steps below:
1. Open **Insights** and the respective page where you want to schedule a report.
2. To download individual reports, click on the **Export report** button next to the analytics.
3. To schedule a report to receive email alerts, click **Schedule report**.
4. On the side panel, configure the following:
- **Frequency**: You can choose hourly, weekly (select the days of the week that the report needs to be sent on), monthly or quarterly (choose timezone and dates).
- **Email**: Specify the email IDs of the recipients to which the report needs to be sent. You can add up to a maximum of 10 email IDs (they can also be external to your organization).
- **Subject**: Subject is pre-filled with the report name.
- **Message**: Type in a message that you want to add to the body of the email.
5. After configuring the details, you can send a test email to check if the format of the email is as expected, this test email is sent out to the entered email idea.
6. Click **Save**. This report will be sent to the respective email IDs as per the schedule.
> Expect a few minutes of delay when sending a large file.
> Links to reports sent via email are only valid for 15 minutes.
---
## Retrieving Session Data from the Data Explorer
This guide explains how to retrieve data from **Insights > Data Explorer** within the **User Engagement Events** table.
---------
## User-session data for a specific date
1. Filter the Timestamp.
2. Filter the **Event** as *user-session*.
****
3. Click **Apply** to view the user-session data. This will display details such as User IDs, chat URLs, and session IDs.
****
--------
## Count User-Sessions
1. Click Summarize. Choose Summarize by count.
2. Set Timestamp by day/week/month.
****
****
****
-----
## Access Agent-Session Data
1. Filter the Timestamp.
2. Select the **Event** as *agent-session*.
3. Set **Session ID** as *not empty*.
****
****
****
--------
## Calculate bot sessions
To calculate bot sessions, subtract agent-sessions from total user-sessions:
```
Bot Sessions = Total Sessions (User-Sessions) - Agent-Sessions
```
---
## Key metrics related to sessions
This article guides you through analyzing key metrics related to sessions. These metrics include:
1. Message Count
2. New User Count
3. Unique User Count
4. Session Count
Understanding the type of session—either bot or user session—is crucial for accurate analysis.
**To determine the session type**
1. Right-click on your screen and select **Inspect**.
2. Open the **Network** tab and search for the keyword "Insights."
3. Refresh the page and examine any API call's payload to determine the session type. By default, it is set to a bot session.
--------
## Message Count
To analyze message counts:
| **Bot Session** | **User Session** |
| -------- | -------- |
| 1. Open **Data Explorer > Message Events** table. 2. Apply a filter for **Interaction Type = welcome-reply**. 3. Summarize the data based on the **Sum of Count**. | 1. Open **Data Explorer > Message Events** table. 2. Apply a filter for **Interaction Type != welcome**. 3. Summarize the data based on the **Sum of Count**. |
****
-------
## New User Count
To analyze new user counts:
| **Bot Session** | **User Session** |
| -------- | -------- |
| 1. Open **Data Explorer > User Engagement Events** table. 2. Apply a filter for **Event = first-message** or **Users-visited**. 3. Summarize the **Count**. | 1. Open **Data Explorer > User Engagement Events** table. 2. Apply a filter for **Event = first-message**. 3. Summarize the **Count**. |
> You can also apply filters based on channels and timestamps.
****
---
## Unique User Count
To calculate the unique user count:
| **Bot Session** | **User Session** |
| -------- | -------- |
| 1. Open **Data Explorer > Message Events** table. 2. Apply a filter for **Type = bot-message**. 3. Summarize the data based on **Distinct UID**. | 1. Open **Data Explorer > Message Events** table. 2. Apply a filter for **Type = user-message**. 3. Summarize the data based on **Distinct UID**. |
****
-----
## Session Count
To count sessions:
| **Bot Session** | **User Session** |
| -------- | -------- |
| 1. Open **Data Explorer > User Engagement** table. 2. Apply a filter for **Event = bot-session**. 3. Summarize the **Count**. | 1. Open **Data Explorer > User Engagement** table. 2. Apply a filter for **Event = user-session**. 3. Summarize the **Count**. |
****
---
## Steps to identify all the triggered intents of the bot
By gaining insights into all the intents triggered by the bot, you can draw multiple conclusions, such as:
* Analyzing the most and least triggered intents provides insights into user interactions and preferences.
* Identifying key intents helps in understanding the primary goals and needs of users.
* Monitoring the frequency of assistance requests or user satisfaction gauges the effectiveness of the bot's performance.
* Utilizing data for training purposes enhances the bot's capabilities and accuracy over time.
In this article, you will learn a workaround to obtain all the triggered intents (from which you can deduce the top triggered intents).
## Obtain all the intents triggered
Follow the steps below to obtain the triggered intents and confidence level of the predicted intent:
**Step 1 (initial flow):**
1. Add a start node and a text/question node that displays a message.
2. Connect to an execute flow node to track intents.
**Step 2 (add flow to initiate a skill):**
In this flow (e.g., intent trigger analytics), you can create a skill (execute flow) to identify the intents.
**Step 3 (create a database):**
1. Open Automation > Database.
2. Create a table and add searchable columns to store the intent names.
This table will be available in Data explorer.
**Step 4 (create a skill):**
> Click [here](https://docs.yellow.ai/docs/platform_concepts/studio/dynamicchatnode#skill-configuration) to learn how to configure a skill.
1. Create a new skill.
2. Connect the start node to a function node and add the below function which fetches the intent names (slug value) and confidence from the `data.prediction.intents` variable.
```
return new Promise(resolve => {
// Your logic goes here
let intent_name, intent_confidence, intent_array = [];
let intentsObject;
try {
console.log("data Obj" + JSON.stringify(data));
console.log("data prediction Obj" + JSON.stringify(data.prediction));
intentsObject = data.prediction.intents;
for (let eachKey of Object.keys(intentsObject)) {
if (intentsObject[eachKey] > 0.87) { //
switch (eachKey) {
case "uSN404cibhVyphu_LAG-u": // ADD YOUR SLUG NAME HERE
intent_name = "talk to agent"; // ADD YOUR INTENT NAME HERE
intent_confidence = "" + intentsObject[eachKey];
break;
default:
intent_name = "Unknown Intent | " + eachKey;
intent_confidence = "Uknown Confidence";
break;
}
intent_array.push({
"intentName": intent_name,
"intentConfidence": intent_confidence
});
}
}
}
catch (e) {
console.log("On Error Block : " + e);
intent_name = "No Intent";
intent_confidence = "No Confidence";
intent_array.push({
"intentName": intent_name,
"intentConfidence": intent_confidence
});
}
resolve(intent_array);
});
```
3. Store the output in an object variable, e.g., intents_arr. The value of which will be the Intent slug names and the confidence.
4. Connect to another function node and add the below function to identify and segregate if more than one intent-confidence value is recognized from one input (i.e., if an array of values is identified in a variable intent_arr).
```
return new Promise(resolve => {
// Your logic goes here
let current_prediction_array = data.variables.intents_arr;
current_prediction_array.shift();
resolve(current_prediction_array);
});
```
5. Create 2 variables using a variable node to segregate the object variable to two different values such as predicted_intent_name and predicted_intent_confidence `{{{variables.intents_arr.0.intentName}}}` and `{{{variables.intents_arr.0.intentConfidence}}}`.
6. Use a condition node to check if the intent value recognized is set.
7. Connect the condition node to the database node and store the variables into the columns (intents and confidence).
8. The following nodes/connections are an example of the skill that must be configured.
:::note
Insights related to frequently asked questions (FAQs) cannot be obtained through this process as each question necessitates a distinct flow.
:::
### Filter for top triggered intents
To gain insights into top intents, you can generate [custom analytics](https://docs.yellow.ai/docs/platform_concepts/growth/dataexplorer/customtables) based on the custom table you've created. This analytics allows you to determine which flows are frequently triggered and the frequency of these triggers.
> You can apply custom analytics only if the columns in the database are **searchable**.
1. Open Insights > Data Explorer.
2. From custom tables, select the table which has intent data.
3. Filter the data for particular keywords.
4. Summarize by > count of intent names. This will give you the count of all the intent names triggered.
5. You can sort this column to get the most triggered intents vs least triggered intents.
:::note
The **Top flows viewed** widget in the Insights > Overview section provides information about the most frequently initiated sequences of actions within the platform. While the most viewed flows might be those promoted as default options, the most triggered flows are determined by actual user interactions, taking into account various entry points like start points and in-flow buttons.
:::
---
## Google sheet integration for dynamic record update
This guide will walk you through integrating Google sheets with your AI-agent to automatically update records based on user interactions.
**Scenario**
Consider that you have created a [campaign](https://docs.yellow.ai/docs/platform_concepts/engagement/outbound/outbound-campaigns/run-campaign) to notify users about current offers, and you want to automatically update a Google sheet with user interaction details when the campaign is sent. The goal is to capture and insert the following information into the Google sheet:
* **Template name**: Name of the template used in the campaign.
* **Quick reply clicked**: User's selected quick reply option.
* **Campaign ID**: Unique identifier for the campaign.
* **User phone number**: Contact number of the user.
* **Timestamp**: Date and time of the interaction.
**Prerequisites**
Consider the following prerequisite to automatically update records in Google sheet:
* **Google sheets integration**: Configure the integration with [Google sheets](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/google-sheets#scope-of-integration).
* **Create an event**: Set up an [event](https://docs.yellow.ai/docs/platform_concepts/studio/events/event-hub) in the **Engagement** section to trigger the data capture flow.
### Steps to automatically update a Google sheet
To configure a bot flow that dynamically updates a Google sheet based on user interactions, follow these steps:
1. Go to the flow editor and select the start trigger type as **Event** and choose the event that you have created.
2. Add a Variable node to store to store all template values retrieved from the quick reply event and the values of the Google sheets nodes:
* **spreadSheetID**: Unique Google Sheet ID.
* **range**: Defines the cell range for data insertion/deletion/updates.
* **majorDimension**: Specifies how data is should be arranged (ROWS or COLUMNS).
3. To append new entries in new rows and to avoid overwriting existing records, use the **Google sheets** node to retrieve existing sheet data and store the result in an object variable.
Sample success response of GetValuesFromSheet:
```c
{
"spreadsheetId": "1FXBz2k8m9Ys3zkJy6n8G4237q1x43Tq4nu6CdM1A66Y",
"valueRanges": [
{
"range": "Sheet1!A1:A5",
"majorDimension": "COLUMNS",
"values": [
[
"J",
"O",
"H",
"N"
]
]
}
]
}
```
4. Connect **Analytics** node to the Google Sheets node’s fallback to capture any errors or event data for further analysis.
5. After retrieving the sheet records, add a Function node to insert the data. The function node performs two operations:
* **Adjust the range value**: The function increments the row index by +1 to ensure new data is inserted into the next available row, avoiding any overwriting of existing records.
* **Output**: The function's output should be saved in an object variable that includes the array of values to be inserted into the sheet and the updated range for data placement.
A sample code to get the total length of records and to populate an array variable for inserting the records in the sheet:
```c
return new Promise(resolve => {
// Your logic goes here
let templateName = data.variables.template_name
let phone = data.variables.phone
let campaignid = data.variables.campaignId
let qrclicked = data.variables.QRclicked
let currentTime = new Date();
let currentOffset = currentTime.getTimezoneOffset();
let ISTOffset = 330; // IST offset UTC +5:30
let ISTTime = new Date(currentTime.getTime() + (ISTOffset + currentOffset) * 60000);
console.log(ISTTime, " istToday ")
let hoursIST = ISTTime.getHours()
let minutes = ISTTime.getMinutes()
// console.log(hoursIST, " hoursIST ")
// console.log(minutes, " minutes ")
let date = ISTTime.getDate()
let month = ISTTime.getMonth() + 1
let year = ISTTime.getFullYear()
let day = ISTTime.getDay()
console.log(month, "month ==")
console.log(day, "day ==")
let d = `${date}/${month}/${year}`
let t
if (hoursIST >= 0 && hoursIST < 12) {
t = " AM";
} else if (hoursIST >= 12 && hoursIST < 24) {
t = " PM";
}
let time = `${d}, ${hoursIST}:${minutes} ${t}`
console.log(time, " time ")
let myArray = [
[phone],
[qrclicked],
[templateName],
[campaignid],
[time]
]
console.log(myArray, " ==== my array ====")
let y = data.variables.obj.valueRanges[0].values.length
// console.log(data.variables.obj, " === data.variables.obj")
console.log(y, "====== Number of Records =====" )
//Range = Main!A:Z
let range = `Main!A${y + 1}:Z`
let obj = {
"a": myArray,
"b": range
}
console.log(obj," === obj ===")
resolve(obj);
});
```
6. Add a Variable node to modify the **majorDimension** variable to "COLUMNS". This ensures each array record is added to a separate column within the sheet.
**Example**: If your data is:
```
[
[1, 2, 3],
[4, 5, 6]
]
```
* If major dimension is rows the data in the sheets will be added as vertically
* If the major dimension is COLUMNS then the data shall be added as horizontally.
7. In Google sheets nodes, define the following:
1. Select **Insert/UpdateValuesInSheet** option from Google Sheets node.
2. Pass the parameters such as majorDimension, Range (updated value from step 5), values (data array to be inserted), spreadSheetID.
3. Store the node output in an object variable.
8. Connect **Analytics** node to the Google sheet's node fallback. This node will capture the event name and error response for analysis.
The screenshot below illustrates how user interaction data from a campaign is automatically inserted into a Google sheet:
---
## Parse API response field
The Parse API response field helps you extract the important information from an API response.
Let's say that you receive a response that looks like this,
```
{
"body": x,
"status": y
}
```
and you only need the **body** part, you can use the **Parse API response** node to filter out and extract the **body** information.
:::info
For example, you made a request to an API to get a list of people along with their contact information. The API will send back a response containing this data in a specific format.
However, the response might contain more information than you need. For example, if you're only interested in the name and email of the first person in the list, you would need to parse the response. Parsing means to extract only the data you need and convert it into a data structure that you can work with in your code.
Once you have parsed the response, you can access the specific pieces of data that you need. You can then use this information for further processing or display it in your application as needed.
:::
1. To add the code to filter the necessary information from the API response, go to [Functions](https://docs.yellow.ai/docs/platform_concepts/studio/build/code#1) section and click **+Add new function** to add a new function that contains the specific code. This function will be used in the Parse API response node later.
2. Next, go to the integration that receives the API response and locate the Parse API response node. This node filters the response to extract only the required information.
3. In the **Parse API response** field, pass the function you created earlier that contains the code to filter the necessary information. This function will be executed by the Parse API response node to extract the required information from the API response.
Once you have completed the above steps, you should be able to receive a filtered API response that contains only the required information specified in your custom function. You can either use that for further processing or display it to the user.
---
## Banking, Financial Services and Insurance (BFSI) template
> Explore **Banking and finance template** [here](https://cloud.yellow.ai/marketplace/c5e39a30338e3658daf4168937e979c6).
Online banking has now made daily transactional tasks easier for all consumers. Banks are exploring more options to provide user-friendly features through phone and online platforms, resulting in saving time, ease of usage, lower fees, improved customer service and security.
**BFSI template** is designed to accommodate daily banking needs via WhatsApp and other web channels.
**Template use case**
Pre-built use cases accommodate basic online banking features such as creating an account, applying for a loan, checking the loan Status, calculating EMI, and connecting to support for better resolution.
The template can be customized for complex use cases, like digital banking options (paying bills online), or simple ones like applying for a debit card, and viewing transaction history.
:::info
For details on importing and editing the markerplace templates, click [here](https://docs.yellow.ai/docs/platform_concepts/get_started/marketplaceintro).
:::
-------------------
## 1. Prebuilt use cases
The following are the most common use cases (flows) that are prebuilt in this template:
1. **Start**: After providing a brief introduction about the bank and its offerings, this flow provides options to bot users on WhatsApp and the web to Create an account, Apply for a loan, View the Loan Status, Calculate EMI or Connect to support for better resolution.
2. **Create new account**: This flow assists with creating a new savings or current account for the bank customer. It collects customer details like bank account type, name, email ID, phone number, PAN, and Aadhar number. Once the PAN and aadhar numbers are verified, a new account is created.
3. **Apply for Loan**: This flow provides loan options like Car loans, Home loans, and Education loans. It collects the loan requirements such as type of loan, phone number, name, Aadhar card, PAN number, and request loan amount. Aadhar and PAN numbers are verified, and on successful completion, an application is generated.
4. **Loan status**: This flow displays the loan status of the existing loan application(approved, rejected, or other comments) for the entered phone number.
5. **EMI calculator**: This flow calculates the EMIs applicable for the loan amount. It collects the loan amount, rate of interest, and loan tenure. Based on the given details, EMI is calculated.
6. **Connect with support**: This flow provides customer support either by fetching answers from the trained FAQs or by connecting the bot user directly to the support agent to address complex queries.
These flows are explained in detail in the further sections.
:::note
A flow triggers when a particular intent/entity/event/URL is identified or when the [Execute flow](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/execute-flow) node is used in other flows. See [start trigger](https://docs.yellow.ai/docs/platform_concepts/studio/build/Flows/configureflow#configure-start-trigger) for more details.
:::
---
### 1. Start - Display the main menu
1. **Start trigger**: Immediately after displaying the welcome message, **Start** flow is triggered.
- It can also be triggered at any point of the conversation when the bot user types a sentence that matches with the [intent](https://docs.yellow.ai/docs/platform_concepts/studio/train/intents)- ```Main menu options```.
2. **Identify the channel**: A logic node ([channel filter](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/logic-nodes#2-channel-filter) is used to identify the channel in which the bot conversation is happening. Nodes used in the further flow will be based on the channel.
3. **Quick reply buttons to display menu options**: Five menu options (**Create an account, Apply for loan, Loan Status, Calculate EMI, and Connect with support**) are displayed. For WhatsApp, these are shown as Quick reply buttons using the [WhatsApp list](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#22-whatsapp-list) node, and for other channels, these are shown as menu options using the [Quick reply](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#14-quick-replies) node.
#### :pushpin: Tips
- You can add multiple [channels](https://docs.yellow.ai/docs/platform_concepts/channelConfiguration/overview) to your bot to reach out to your users through any mode.
- If you have varied menu options, you can add (or delete) the quick reply buttons and customize what can be displayed in the main menu.
-----------
### 1.2 Create a new account
1. **Start trigger**: This flow is triggered when the bot user selects the **Create an account** button after the menu options are displayed (start flow).
- It can also be triggered at any point of the conversation when the bot user types a sentence that matches with the [intent](https://docs.yellow.ai/docs/platform_concepts/studio/train/intents)- ```Create new account```.
2. **Fetch account type, name, email ID, and phone number**: Using a [carousel](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#16-carousel) - account type is obtained (**savings and current**) and using other prompt nodes - [name](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#12-name), [email](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#15-email) and [phone number](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#13-phone) are fetched and stored in the respective variables - ```account_type, customerName, customerEmail, customerPhone```
3. **Fetch and validate PAN number**:
- With the [Question](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#11-question) node, the **PAN number** is obtained and stored in a [variable](https://docs.yellow.ai/docs/platform_concepts/studio/build/bot-variables) - ```panNumber```.
- [Function](https://docs.yellow.ai/docs/platform_concepts/studio/build/code) - *panValidator* is run and its response is stored in a [variable](https://docs.yellow.ai/docs/platform_concepts/studio/build/bot-variables)- ```isValid```.
- *panValidation* function verifies if the number entered is a 10-digit alphanumeric expression. If the entered format matches the following conditions, the response is returned as *True*.
- The first five characters are letters in which the first three characters are a sequence of AAA-ZZZ.
- The fourth character identifies the type of PAN card holder.
- The fifth character is the first letter of the person's surname.
- Remaining characters are numbers followed by the one alphabet.
- Using a [condition](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/logic-nodes) node, it is validated if the response(```isValid``` variable value) is True. If it is true, PAN is verified. Otherwise, the number must be re-entered.
4. **Fetch and validate Aadhar number**:
- With a [Question](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#11-question) node, **Aadhar number** is obtained and stored in a [variable](https://docs.yellow.ai/docs/platform_concepts/studio/build/bot-variables) - ```aadhar```.
- [Function](https://docs.yellow.ai/docs/platform_concepts/studio/build/code) - *aadharCardValidation* is run and its response is stored in a [variable](https://docs.yellow.ai/docs/platform_concepts/studio/build/bot-variables)- ```isValid```.
* *aadharCardValidation* function verifies if the number entered is a 12-digit regex expression. If the entered format matches ```/^[2-9]{1}[0-9]{3}[0-9]{4}[0-9]{4}$/```, the response is returned as *True*.
- Using [condition](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/logic-nodes) node, it is validated if the response(```isValid``` variable value) is True. If it is true, Aadhar is verified. Otherwise, the number must be re-entered.
5. **Create account and store details in database**: After the PAN and Aadhar numbers are verified, the [database](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/database-node) node is used to store the entered details into the [table](https://docs.yellow.ai/docs/platform_concepts/studio/database) - ```Bank accounts```. Once the record is added, the account is successfully created.
#### :pushpin: Tips
- After the account is created, you can use [message](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/message-nodes1/message-nodes) nodes to display/promote other banking features that the customers can avail immediately.
- Using [prompt](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes) nodes, customer details such as location, salary range, etc. can be obtained.
- You can verify the phone number using [send OTP](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/send-otp) and [verify OTP](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/verify-otp) nodes.
-----------
### 1.3 Apply for loan
1. **Start trigger**: This flow is triggered when the bot user selects the **Apply loan** button when menu options are displayed (start flow).
- It can also be triggered at any point of the conversation when the bot user types a sentence that matches with the [intent](https://docs.yellow.ai/docs/platform_concepts/studio/train/intents)- ```Apply for loan```.
2. **Display available loan types**: Loan types (Car loan, education loan, home loan) are displayed using a [Quick reply](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#14-quick-replies) node. If the loan type does not match with the customer requirement, a custom type can be entered ([question node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#11-question). Entered loan type is stored in a [variable](https://docs.yellow.ai/docs/platform_concepts/studio/build/bot-variables) - ```Loan```.
3. **Fetch phone number and name**: Applicants phone number and name is obtained through [Phone](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#13-phone) and [Name](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#12-name) nodes.
4. **Fetch and validate Aadhar number**:
- With a [Question](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#11-question) node, **Aadhar number** is obtained and stored in a [variable](https://docs.yellow.ai/docs/platform_concepts/studio/build/bot-variables) - ```aadhar```.
- [Function](https://docs.yellow.ai/docs/platform_concepts/studio/build/code) - *aadharCardValidation* is run and its response is stored in a [variable](https://docs.yellow.ai/docs/platform_concepts/studio/build/bot-variables)- ```isValid```.
* *aadharCardValidation* function verifies if the number entered is a 12-digit regex expression. If the entered format matches ```/^[2-9]{1}[0-9]{3}[0-9]{4}[0-9]{4}$/```, the response is returned as *True*.
- [Condition](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/logic-nodes) node validates the isValid variable of the response. If the response is True, Aadhar is verified. Otherwise, the number must be re-entered.
5. **Fetch and validate PAN number**:
- With a [Question](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#11-question) node, **PAN number** is obtained and stored in a [variable](https://docs.yellow.ai/docs/platform_concepts/studio/build/bot-variables) - ```panNumber```.
- [Function](https://docs.yellow.ai/docs/platform_concepts/studio/build/code) - *panValidator* is run and its response is stored in a [variable](https://docs.yellow.ai/docs/platform_concepts/studio/build/bot-variables)- ```isValid```.
- *panValidation* function verifies if the number entered is a 10-digit alphanumeric expression. If the entered format matches with the following conditions, the response is returned as *True*.
- The first five characters should be letters in PAN card where the first three chars are a sequence of AAA-ZZZ.
- The fourth character identifies the type of PAN card holder.
- The fifth character is the first letter of the person's surname.
- The remaining characters are numeric followed by an alphabet.
- [Condition](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/logic-nodes) node validates the isValid variable response. If it is True, PAN is verified. Otherwise, the number must be re-entered.
6. **Select loan amount**: Different loan amounts (1,00,000 and 2,50,000) are displayed using a [Quick reply](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#14-quick-replies) node (to obtain a loan of amount other than the given option, customer can contact the support)The selected amount is stored in a [variable](https://docs.yellow.ai/docs/platform_concepts/studio/build/bot-variables) - ```Amount```.
7. **Display options to modify the entered details**: The entered details which are stored in respective variables are displayed through a [Quick reply](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#14-quick-replies) node and display quick reply buttons to modify the entered details (**Loan type, phone number, name, Aadhar, PAN, loan amount**). Based on the option selected, values are modified. For example, if the name is selected, the name node is prompted and a new name can be entered, which will be stored in the [variable](https://docs.yellow.ai/docs/platform_concepts/studio/build/bot-variables)-```name```.
8. **Create application and store details in the database**: If **No change** button is selected, *applicationNumber* - [function](https://docs.yellow.ai/docs/platform_concepts/studio/build/code) is called and **Application number** is generated. ```Loan application``` [table](https://docs.yellow.ai/docs/platform_concepts/studio/database) is created and all these details (variable values) are inserted into the respective columns.
#### :pushpin: Tips
- Use [prompt](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes) nodes to collect more customer details while applying for a loan.
- You can verify the phone number using [send OTP](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/send-otp) and [verify OTP](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/verify-otp) nodes.
----------
### 1.4 Loan status
1. **Start trigger**: This flow is triggered when the bot user selects the **Loan status** button from the menu options (start flow).
- It can also be triggered at any point of the conversation when the bot user types a sentence that matches with the [intent](https://docs.yellow.ai/docs/platform_concepts/studio/train/intents)- ```Status of my loan```.
2. **Fetch registered phone numbered**: Using the [phone node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#13-phone) the registered phone number is obtained and stored in the ```customerPhone``` variable.
> There must be an existing loan application to check its status.
3. **Search for the application status from the database table**: ```Loan application``` [table](https://docs.yellow.ai/docs/platform_concepts/studio/database) is created with required columns to store all the loan application details and their statuses. Using a [Database node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/database-node) in the flow, the application details of the entered phone number are fetched.
> **Database node**: The response obtained from this node is a result of the **Search** operation performed on the table **Loan application** where the **Phone number** (table's column) matches the ```customerPhone``` (phone number variable entered by the bot user). This response is stored in a variable ```dbresp```.
4. **Display loan status**: Response obtained from the database consists of the status, which is stored in the ```dbresp``` variable. It is displayed using a [Text node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/message-nodes1/message-nodes) and a variable: ``` {{{variables.dbresp.records.0.status}}}```
- If the phone number entered by the customer does not exist (in the ```Loan application``` database), a message - "Application was not found, the application number does not exist." is displayed using a [Text node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/message-nodes1/message-nodes).
#### :pushpin: Tips
- If the loan application does not exist, you can direct the users to apply for a loan.
- This template can be customized to prompt the customer to apply for a loan and display other banking options (like applying for a credit card, EMI, etc.).
-----------
### 1.5 EMI calculator
1. **Start trigger**: This flow is triggered when the bot user selects the **Calculate EMI** button from the menu options (start flow).
- It can also be triggered at any point of the conversation when the bot user types a sentence that matches with the [intent](https://docs.yellow.ai/docs/platform_concepts/studio/train/intents)- ```Calculate loan EMI```.
2. **Fetch Amount, Interest, and Tenure**: [Question nodes](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#11-question) are used to obtain loan amount, specified interest rate, and loan tenure in months, these values are stored in three variables (```selectedLoanAmount```, ```selectedIr``` and ```selectedTenure```)
3. **Calculate and display EMI amount**: A function node is used to calculate EMI with the data obtained through question nodes. With help of a [Text node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/message-nodes1/message-nodes) expected EMI is displayed.
```
EMI = P × r × (1 + r)n/((1 + r)n - 1)
(P= Loan amount, r= interest rate, n=tenure in number of months)
```
#### :pushpin: Tips
- This flow can be cloned and math operations can be used to modify the EMI function to calculate interest obtained on a savings account, current account, fixed deposit, recurrent deposit, etc.
----------
### 1.6 Connect with support
1. **Start trigger**: This flow is triggered when the user selects **Connect with support** quick action from the start menu. This flow can also be triggered when the bot user's input matches with any of the sentences(utterances) trained for the ```chatWithAgent``` [intent](https://docs.yellow.ai/docs/platform_concepts/studio/train/intents).
2. **Display and verify support options (Agent/FAQs)**: With a [carousel](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#16-carousel) node, two options (Chat with support and FAQs) are displayed. The type of support selected is identified using [condition node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/logic-nodes#1-condition). ```@queries_and_concerns``` entity is trained to identify FAQs and Chat with support as ```entity values```.
- If the FAQs option is selected, answers to the user queries will be fetched from the trained FAQs.
- If Chat with support is selected, a support agent will be connected to take the conversation forward.
3. **FAQs**: All the FAQs are added and trained with the answers in the [FAQs section](https://docs.yellow.ai/docs/platform_concepts/studio/train/add-faqs). When FAQs is selected, a condition node ([channel filter](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/logic-nodes#2-channel-filter) is added to identify the channel from which the conversation is taking place.
- If the conversation is happening on WhatsApp, [WhatsApp list](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#22-whatsapp-list) node is used to display the list of FAQs.
- If the conversation is via other channels, [Quick reply](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#14-quick-replies) node is used to display the list of FAQs.
- User can also type the query in the input bar.
- Based on the selection/entry, the answer will be fetched from the trained FAQs.
4. **Chat with support**: [Prompt nodes](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes) are used to fetch the bot user's information such as ```phone number```, ```name```, and ```query```. These details are stored in the [respective variables](https://docs.yellow.ai/docs/platform_concepts/studio/build/bot-variables#31-create-a-variable-via-nodes) and passed into the [Raise ticket](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/raise-ticket) action node, this will connect the user to the support agent.
> Inbox must be set up to connect the bot user to a live support agent. A support agent must be available (online) when the support request is raised. Click [here](https://docs.yellow.ai/docs/platform_concepts/inbox) to learn about Inbox.
#### :pushpin: Tips
- Add/ Delete the number of FAQs listed on the Quick reply node.
- Add [FAQs](https://docs.yellow.ai/docs/platform_concepts/studio/train/add-faqs) based on your industry.
- **Name** and **Query** are the mandatory fields to use a **Raise ticket** node. You can reduce the prompt nodes to avoid collecting details from the users prior or you can add more prompt nodes to collect other details before connecting to the agent.
- As per bank requirements, you can fetch user details (name, email address, number) using **Prompt** nodes even if the user selects FAQs. This data can be used later for acquisition or monitoring purposes.
---
## Ecommerce template
> Explore **E-commerce template** [here](https://cloud.yellow.ai/marketplace/a77bc7a01c7e14698667c09d4c6a2512?name=ecommerce%20whatsapp).
The E-commerce template offers a highly efficient and valuable service for online businesses. It guides your customers through buying products. This includes adding a product to the cart, updating product quantity, adding more products, and proceeding to purchase. Post-purchase, customers can track their order status. The template can handle common customer queries and helps connect with the support team if required.
You can use our platform to build custom flows for your business use cases. For example, promote products, show store location, showcase products from your database, enable single sign-on from your e-commerce site, and more.
Here is the high-level overview of the e-commerce template:
:::info
For details on importing and editing the markerplace templates, click [here](https://docs.yellow.ai/docs/platform_concepts/get_started/marketplaceintro).
:::
## 1. Prebuilt use cases
This section covers all the standard use cases available in the e-commerce template.
### 1.1 Browse products
The flow displays the list of product categories along with its products and help users with the purchase.
Here are the details of the **Browse products** flow:
1. Starts with the intent *View available products*.
2. **Verifies channel**: Applies the **Channel filter** to check if the user is from YellowMessenger or from other channels.
3. Uses the **Function** node to fetch the list of product categories from the **Database**.
If the channel is WhatsApp, it shows the list of product categories using the **WhatsApp list** node.
4. Selecting the product category shows the list of products in that category.
For the WhatsApp channel, it uses **Function**, **Variables**, and **Modifier** nodes to display the list of products.
### 1.2 Add to cart
This flow is executed when the bot user selects a product to add to the cart. The user can add each product along with the quantity and proceed to buy once all the required items are added to the cart.
1. **Triggers flow** when the user selects *Add to cart* on the **Browse products** flow.
2. **Shows quantity**: Each product is associated with the product ID. Based on the selected product [Condition node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/logic-nodes), it shows an option to select the quantity (**Quick replies** for web and **WhatsApp list** for WhatsApp).
3. **Adds to cart**: Verifies the quantity and product ID and fetches the product from the database (**Database** node) and adds the item to the cart (`addToCart` function).
4. **Shows cart summary**: Calculates the cart price (Price associated with the Product ID * quantity = Total Price) and renders the cart details using the `formatCartSummary` **Function** node along with these options (**Quick replies**)
* [Buy now](#15-buy-now), [Edit cart](#13-edit-cart), [Clear cart](#14-clear-cart) and Add more products. It triggers the respective flow based on the input.
### 1.3 Edit cart
This flow allows users to edit the current cart details - change the quantity or remove a product from the cart.
1. **Triggers** when the user selects **Edit cart** is selected on the **Add to cart** flow.
2. **Verifies cart items**: Checks if the cart is empty using the `IsCartEmpty` (**Function** and **Condition** nodes).
* If it is empty, the user will be directed to the Browse products flow.
* If the cart is not empty, it shows the current cart details (`ShowCart` function) of the user.
3. **Edit cart**: Uses the **Carousel** node to display the summary of the existing cart (all the items with quantity and price) along with the options to edit the item quantity and remove the item (for each item with a unique product ID). It shows up relevant options based on the user input (**Condition** node).
4. **Edit item**: Allows editing the quantity (for that product ID) using **Quick replies** (and **WhatsApp list**).
Stores the new quantity using the `editcart` function in a variable and updates it in the database (user details).
5. **Remove item**: Removes the item from the cart using the `editcart` function and the new cart summary is updated in the database (user details).
6. **Shows options to proceed**: Shows these **Quick replies** and clicking on it executes the respective flow [Buy now](#15-buy-now), [Clear cart](#14-clear-cart) and [Add more products](#12-add-to-cart).
### 1.4 Clear cart
The flow triggers when the user selects *Clear cart* from the bot flows. The cart is cleared, and all the item details (Product IDs and Quantity) stored in the user database will be deleted.
1. **Triggers the flow** with the intent `clearCart` when the user selects the *Clear cart* option from any flow.
2. **Clears the cart**: Cart variable is assigned to [], which means the details present in the cart becomes null.
4. **Updates user details**: The database (user details) is updated to empty the cart. A text node is displayed to the user confirming that the cart is empty and shows the Browse products option.
### 1.5 Buy now
This flow generates the payment link using the cart details and sends the payment link to the bot user.
1. **Starts** the flow using the intent *buyNow*.
2. **Verifies if the cart is empty**: Uses the **Function** and **Condition** nodes to ensure the cart is not empty before proceeding to the payment.
3. If the cart is empty, it shows the *Browse products* option.
4. If the cart is not empty, it captures the following information required for the order to process.
a. Name and phone number using the respective prompt nodes.
b. Address using the **Location** node and converts it using the `addressConverter` function. User can just share the location from the device.
5. **Generates the payment link**: Passes these details in the `paymentlinksinput` along with the amount (variable) to the **Razorpay** node to generate the payment link.
* Captures the `paymentId` (Variables) and updates two database tables:
* `order_details` with information userId, phone number, cart details, order ID, order value, order status, shipping address, and the payment ID.
* `user_details` table with information cart details, name, phone number, and address.
> * Customise the fields that you want to capture. You can modify column names, add more columns or update existing columns.
> * Use APIs to fetch or update details from an external database.
* Generates the payment link and sends it to the user.
### 1.6 Razorpay payment status
1. Starts with *Razorpay payment status* intent.
2. **Validates the payment status**: Captures the `paymentId` and the value of the `paymentEvent` to validate the payment status (**Condition** and **Variables**).
The following are the different payment statuses supported:
a. `payment_link_paid` - Payment successful
b. `payment_link_canceled` - Payment canceled
c. `payment_link_expired` - Payment link expired
d. Any other status
3. **Updates the order status** (`order_details` variable) in the database (Database node).
### 1.7 Check order status
1. **Starts** when the user selects *View order status* from the bot flow.
2. **Applies channel filter**: Verifies the channel from which the flow is triggered using the **Channel filter** node - WhatsApp and Other channels.
* For the WhatsApp channel, it uses the WhatsApp number and fetches the last five orders of the customer from the database (using the **Function** node).
* For channels except for WhatsApp, it captures the phone number of the user (Phone number node) and uses it in the **Function** node to fetch the last five orders of the customer from the database.
### 1.8 Queries and concerns
With this flow, users can get instant answers through FAQs or choose to chat with the support team.
1. **Triggers** when the user selects *Queries and Concerns* from the menu options.
2. **Shows support options**: Shows *FAQs* or Chat with support options using **Quick replies**.
3. **FAQs**: Shows questions using the **Quick replies** node. When the user types a question or selects from the options, it fetches the response from the [Trained FAQs](https://docs.yellow.ai/docs/platform_concepts/studio/train/add-faqs) list.
> Add more such questions as **Quick reply** options or directly train them on the FAQ page.
> Show more support options if required such as Ask the community, and Refer to docs.
6. **Chat with support**: Captures the user information using [prompt nodes](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes) and uses it to fetch the user details. It also captures the query using the [prompt node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes) and creates a ticket assigning it to an Inbox agent ([Raise ticket](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/raise-ticket) node). The chat is handled by the [Inbox module](https://docs.yellow.ai/docs/platform_concepts/inbox).
## 2. Build your own flows
* **Promote products**: Use the bot as a lead-generation tool. You can send offers, promote new products, and offer instant discounts to your leads through Outbound/Workflow campaigns.
* **Show store location**: If you are running both offline businesses, you can allow your users to find the nearest store location and address using location or zip code. Use **Database** to store all your locations or make use of APIs to fetch directly from external systems.
* **Showcase products from your database**: Use [APIs](https://docs.yellow.ai/docs/platform_concepts/studio/api/add-api) and [Functions](https://docs.yellow.ai/docs/platform_concepts/studio/build/code#docusaurus_skipToContent_fallback) to access data from an external database directly. You can update order/user details, retrieve details, or show any other information that you want your users to access.
* **Enable single sign-on**: Make use of the [API](https://docs.yellow.ai/docs/platform_concepts/studio/api/add-api) or [Database](https://docs.yellow.ai/docs/platform_concepts/studio/database) modules and pass a custom script that can read data from your e-commerce site and pass it to the bot every time the user opens the bot.
---
## EdTech template
## 1. Introduction
Educational firms often get a lot of enquiries about their courses and offerings.
The EdTech template provides a complete chat interface with prebuilt flows that helps Educational Technology firms automate query handling, user acquisition, user communications, and user retention.
With this you can automate handling user inquiries, user support, and lead generation process.
You can completely customize the template according to your business requirement. For example, customize dialogues used in conversations, update courses and their structure, enable OTP-based authentication or single sign-on options. show course discounts, take elaborative quizzes, add FAQs, and more.
Explore **Edtech(education) template** [here](https://cloud.yellow.ai/marketplace?industries=Ed-tech).
:::info
For details on importing and editing the markerplace templates, click [here](https://docs.yellow.ai/docs/platform_concepts/get_started/marketplaceintro).
:::
## 2. Prebuilt use cases
The EdTech template covers the most common use cases targeted for students as explained in the following flow diagram:
### 2.1 Discover courses
You can show the list of courses that you offer and when the user selects a specific course, show the course menu.
Let’s see the **Discover courses** flow in detail:
1. Starts the flow when the user selects *Discover courses* (intent *List all courses*).
2. **Displays courses offered**: Shows the list of courses offered using the **Carousel node** and stores the user response in the variable `subjectname`.
> * Customize the course names as required. You can add more items or remove existing items as needed.
3. **Validates user input**: Uses the **Condition node** to validate the user selection. If-else logic is applied to trigger the *Maths main menu*, *Science main menu, and History main menu* flows based on the user input.
:::note
History, Maths and Science main menus follow the same structure.
:::
4. **Shows the carousel image with relevant options**: *Overview*, *Fee structure*, and *Apply now* options using the **Carousel** node and triggers a specific flow based on the user input.
> * Here, you can modify the condition and define your own custom flows.
5. **Maths overview flow**: Uses Image and Text nodes to display course overview and shows *Reviews*, *Fee structure*, and *Apply now* options (**Carousel**).
1. Validates the user input (**Condition**) and triggers the relevant flow.
2. Selecting Reviews shows up the link of the *Reviews* page (Text node) and triggers the **Followup** flow. The flow has two options linked to the respective flows - [Connect with Counselor](#24-connect-with-support) and *Back to Main menu* (**Carousel**).
> * You can add your own link or perform other actions like trigger a flow, show carousel, show videos etc.
3. Selecting *Apply now* shows a text node and triggers the **Book a demo class** flow.
4. Selecting *Fee Structure* triggers the **Fee structure** flow. This flow shows information using **Text** and **Image** nodes along with the **Followup flow**.
> * There is currently a blank PDF for the fee structure. You can either provide your fee structure or use some other actions like trigger flow, provide link etc.
### 2.2 Course material
You can show the course material in a file that the user can download to the users who registered for the course.
Let’s see the **Course material** flow in detail:
1. **Starts** with the intent `Show me the course material`.
2. **Captures user identifier**: Shows a text message followed by the **Phone Prompt **node and stores it in the `PhoneNo` variable.
> * You can use email or other prompt nodes to identify the user.
3. **Verifies if the identifier is registered**: Searches if the specified phone number is registered in the leads table (Database node) and stores the registered user details in the user_validation object variable.
Leads is a table created inside the **Database** module that contains these fields - Name, phone number, email address, course, subscription status (Demo, Active, or Inactive), record inserted date, and record updated date.
> * You can add new columns or remove an existing column according to your requirement.
> * Use APIs to send and receive information from third-party systems.
4. **Allows registering new users**: If the user is not registered, it shows the Register now option, along with the Main menu and Try again options (Quick replies node).
a. Selecting Register now executes the flow [Book a demo class](#23-book-a-demo-class) and updates the leads database.
b. Selecting the Main menu triggers the **Start flow**.
5. Shows the file for registered users: If the user is registered, it shows the list of courses available (Carousel node), and based on the user input (Condition node) it shows the relevant course material (File node) that the user can download (PDF file).
> * Customize the list of courses that you offer and upload the respective course materials.
> * You can use Document to upload course materials and take advantage of Q&A where the system can extract most relevant answers from the uploaded documents automatically.
### 2.3 Book a demo class
This is a lead generation flow where users can book for a demo class. Post the demo class, you can provide an option to register for the complete course.
Let’s see the **Book a demo class** flow in detail:
1. **Starts** with the intent `Book a demo class`.
2. **Captures user information**: Shows a **Text** node followed by Name, Phone number, and Email nodes and stores the user’s response in the respective variables.
> * Modify the text that you want to show up when the flow starts.
> * Capture more details if required using the relevant nodes. You can skip any prompt (name, phone number, or email) if not required for your use case.
4. **Validates user information**: Shows the details provided by the user. The user can verify the details provided and modify if required information using *Edit name, Edit email, Edit phone number*, and *No changes* (**Quick replies node**).
* This flow is to allow users to verify if the details provided are correct. Any changes the user makes through the respective edit options will update the values in the database accordingly.
5. **Displays list of courses**: Selecting the *No changes* option sets the variable value for subscription as Demo and shows the list of courses (**Quick replies**).
6. **Displays slots**: Shows the slots available for the selected course using the **Condition** node.
7. **Updates user information**: Updates the leads database (**Database** node) with the name, email address, phone number, and subscription status followed by a confirmation text message.
### 2.4 Connect with support
You can allow your users to connect to an education counselor to address their queries.
Let’s see the **Connect to a counselor** flow in detail:
1. Triggers the Connect with support agent intent and shows two options - Chat with support and FAQs.
2. Here is how the Chat with support flow works:
a. **Collects user information**: Asks for the user’s name, mobile number, and email address using the respective **Prompt nodes**.
> * You can customize the information that you want to capture.
b. **Asks for reason**: Shows a predefined list of reasons before connecting to the support - **Cancel Membership**, **Get career related advice**, **Talk to support specialist**.
c. If the user selects *Cancel membership*, it triggers the **Cancel Membership** flow where it captures the reason for cancellation and updates the subscription status in the **Database**.
d. **Connects to the support**: If the user selects *Get career related advice*, or *Talk to support specialist*, it [connects to the live agent](#24-connect-with-support).
e. If the agent is offline, a new ticket is created.
3. **FAQs flow**: It fetches answers quickly from the list of FAQs added through the [FAQs module](https://docs.yellow.ai/docs/platform_concepts/studio/train/add-faqs).
a. Shows a list of frequently asked questions the user can select (**Quick replies node**).
b. Fetches replies based on the selected question.
> * You can keep the questions open-ended if required. Import FAQs in bulk using the [FAQs module](https://docs.yellow.ai/docs/platform_concepts/studio/train/add-faqs#2-add-faqs-in-bulk) and the bot shows up the answer based on the keywords. You can then connect if he still wishes to contact support.
### 2.5 Take a quiz
You can allow the user to select the course that he is interested in, and show questions related to the course. Recommend the course levels according to their current knowledge. For example, recommend the basic course for answering basic questions incorrectly, recommend a basic course, if they answer basic questions correctly, recommend an advanced training course.
Let’s see the **Take a quiz** flow in detail:
1. Starts with Take a quiz intent.
2. **Shows the list of courses**: Shows a text message followed by the list of courses to select from (Quick replies node).
3. **Displays question**: Shows the relevant question with multiple answers (Quick replies node) for the selected course.
4. **Recommends course level**: Recommends the course level based on the answer and provides discount codes (Text node).
5. Provides options *Retake quiz* (if user selects incorrect answer) and *Book a demo* using Quick replies.
6. Selecting *Book a demo* triggers [Book a demo class](#23-book-a-demo-class) flow and *Retake quiz* goes back to step 3.
## 3. Build your own use cases
Along with the prebuilt flows, you can create your own flows for your business specific use cases using [Studio](https://docs.yellow.ai/docs/platform_concepts/studio/overview) and other modules of Yellow.ai.
Here are some EdTech specific templates:
- **OTP verification for qualifying leads**: You can validate your registered user details through OTP based authentication using the Send OTP and Verify OTP action nodes.
- **Send campaigns to promote new courses**: Use the bot as a good lead generation tool. You can send course information, promote new courses, or offer discounts on existing courses to your leads through [Outbound campaign](https://docs.yellow.ai/docs/platform_concepts/engagement/outbound/outbound-campaigns/run-campaign) or [Workflow campaigns](https://docs.yellow.ai/docs/platform_concepts/engagement/flows_campaign).
- **Take feedback/review on courses**:
You can create a flow to capture feedback from users. Provide an option to select the course, and list down the feedback options to select with a text box. Create a database table to store the user response.
- **Single sign-on**: Make use of the API or Database modules and pass a custom script that can read data from your website and pass it to the bot directly every time the user opens the bot.
- **Provide more study material**: You can use [Documents](https://docs.yellow.ai/docs/platform_concepts/studio/train/what-is-document-cognition) feature available in Studio to upload your documents and generate FAQs from them.
For example, it can open the document and navigate to the specific page and section that the user has searched for.
- **Take elaborate career quizzes**: You can increase the number of questions and complexity in a quiz. You can do assessment post completing the courses.
* **Use APIs to send or receive data**: You can also use [APIs](https://docs.yellow.ai/docs/platform_concepts/studio/api/add-api) to send or receive data according to your preference from third-party systems. With the API feature, you need not sync or import the entire data to yellow.ai platform.
---
## Healthcare template
> Explore **Healthcare template** [here](https://cloud.yellow.ai/marketplace/41d196469e2c531ec23971260e070663).
The **Healthcare** template provides quick and convenient access to information about your healthcare services, appointment scheduling, and patient registration. This article walks you through the features of the template and help you in enhancing your overall healthcare experience.
:::info
For details on importing and editing the markerplace templates, click [here](https://docs.yellow.ai/docs/platform_concepts/get_started/marketplaceintro).
:::
-------------------
## 1. Prebuilt cases
The following are the most common use cases (flows) that are prebuilt in healthcare template:
1. **Start:** This flow offers the options for a new patient to register, book a consultation, view clinics closer to their place, collect medical reports and reach out to support for personalised queries.
2. **New patient registration:** This flow collects the details of a new patient, for example, name, age, contact number, gender, email address and stores it in a database.
3. **Book a consultation:** This flow assists your users in scheduling an appointment with your healthcare centre by collecting the date and time of the doctor you would like to consult.
4. **Locate nearby clinics:** This flow collects the user's location details and shows the clinics closer to their place.
5. **Collect report:** This flow helps your users collect their health reports by accessing their electronic records.
6. **Connect with support:** This flow provides customer support either by answering user questions from the trained FAQs or by connecting the bot user to the support agent to address complex queries.
-------------------
### 1.1 Start - Display the main menu
1. **Start trigger**: It is triggered immediately after the welcome message.
- It can also be triggered at any point of the conversation when the bot user types a sentence that matches with the [intent](https://docs.yellow.ai/docs/platform_concepts/studio/train/intents) - ```Main menu options```.
2. **Identify the channel**: A logic node ([channel filter](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/logic-nodes#2-channel-filter)) is used to identify the channel in which the bot conversation is happening. Nodes used in the further flow will be based on the channel.
3. **Quick reply buttons to display menu options**: Six menu options (**New Registration, Book a consultation, Locate nearby clinics, Collect reports, and Connect with support**) are displayed. For WhatsApp, these are shown as Quick reply buttons using the [WhatsApp list](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#22-whatsapp-list) node, and for other channels, these are shown as menu options using the [Quick reply](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#14-quick-replies) node.
#### :pushpin: Tips
- You can add multiple [channels](https://docs.yellow.ai/docs/platform_concepts/channelConfiguration/overview) to your bot to reach out to your users through any mode.
- If you have varied menu options, you can add (or delete) the quick reply buttons and customize what can be displayed in the main menu.
-------------------
### 1.2 New patient registration
1. **Start trigger:** This flow is triggered when the bot user selects the **New patient registration** button when menu options are displayed (start flow).
It can also be triggered at any point of the conversation when the bot user types a sentence that matches the intent - ```New patient registration```.
2. **Fetch name, age, gender, email ID, and phone number**: Using prompt nodes - [name](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#12-name), [question](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#11-question), [email](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#15-email), [phone number](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#13-phone), and [gender](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#14-quick-replies) are fetched and stored in the respective variables - ```name, selectedAge, selectedGender, phoneNo, email```.
3. **Verify patient details:** The [quick reply](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#14-quick-replies) node displays all retrieved information, such as name, age, gender, email, and phone number, and allows users to modify it. If you select **No change** option, then your data will be stored in the database.
4. **Storing new patient details in the database:** After the details are modified, the [Database](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/database-node) node is used to store the entered details in the table - ```Patient details```. Once the records are added, a success message is displayed using text node .
#### :pushpin: Tips
- You can collect more details - previous medical details and upload files.
- Using [execute flow](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/execute-flow) and [QR nodes](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#14-quick-replies) you can display the next options available for the patient registration.
----------
### 1.3 Book a consultant
1. **Start trigger:** This flow is triggered when the bot user selects the **Book a consultant** button when menu options are displayed.
It can also be triggered at any point of the conversation when the bot user types a sentence that matches the intent- ```Book an appointment```.
2. **Capture email ID of the patient:**
- Using a [Question](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#11-question) node, **email ID** is obtained and stored in a [variable](https://docs.yellow.ai/docs/platform_concepts/studio/build/bot-variables) - ```emailId```.
3. **Fetch the branch details from the database:**
- [Database](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/database-node) - From the doctor details table, the database node will fetch unique branch names, which are stored in a [variable](https://docs.yellow.ai/docs/platform_concepts/studio/build/bot-variables) - ```branch```.
- [Function](https://docs.yellow.ai/docs/platform_concepts/studio/build/code) - branch function is used to display the branch names, which are stored in the [variable](https://docs.yellow.ai/docs/platform_concepts/studio/build/bot-variables) - ```branch_qr```.
- [Quick reply](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#14-quick-replies) node is used to fetch a list of branch names from the ```branch_qr``` variable and display the branch names in the form of quick reply buttons.
4. **Fetch the doctor's specialization from the database:**
- [Database](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/database-node) - From the doctor details table, the database node will fetch all the details of doctors from the previously selected branch, which are stored in a [variable](https://docs.yellow.ai/docs/platform_concepts/studio/build/bot-variables) - ```doctor```. These records are sent to the function.
- [Function](https://docs.yellow.ai/docs/platform_concepts/studio/build/code) - ```speciality``` function is used to display the doctor's specialization, which is stored in the [variable](https://docs.yellow.ai/docs/platform_concepts/studio/build/bot-variables)- ```speciality_qr``` in the form of quick reply buttons.
- [Quick reply](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#14-quick-replies) node is used to fetch a doctor's specialization from the ```speciality_qr``` variable and display the branch names in the form of quick reply buttons.
5. **Fetch the doctor's details from the database:**
- [Database](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/database-node) - From the doctor details table, the database node will fetch all the details of doctors from the previously selected branch and doctor specialization, which are stored in a [variable](https://docs.yellow.ai/docs/platform_concepts/studio/build/bot-variables) - ```doctor```. These records are sent to the function.
- [Function](https://docs.yellow.ai/docs/platform_concepts/studio/build/code) - doctor function is used to display the doctor's name, which is stored in the [variable](https://docs.yellow.ai/docs/platform_concepts/studio/build/bot-variables) - ```doctor_qr``` in the form of quick reply buttons.
- [Quick reply](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#14-quick-replies) node is used to fetch a doctor's name from the ```doctor_qr``` variable and display the branch names in the form of quick reply buttons.
6. **Display date and time slot for appointment:**
- [Date](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#21-date) node is used to select a single date and store it in the [variable](https://docs.yellow.ai/docs/platform_concepts/studio/build/bot-variables)```dt```.
- [Quick reply](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#14-quick-replies) node, is used to select a morning or evening slot for the users.
- [Function](https://docs.yellow.ai/docs/platform_concepts/studio/build/code) - timeslot function is used to display morning or evening timeslots, for example- 9 AM - 10 AM.
7. **Store details in database and confirm booking:** After all the details are fetched, a booking ID is generated - ```bookappointresponse``` function.
- A [database](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/database-node) node is used to store the entered details in the table -```Booking details```. Once the record is added, your appointment booking is successfully created.
-------------------
### 1.4 Locate nearby clinics
1. **Start Trigger:** This flow is triggered when the bot user selects the **Locate nearby clinics** button when menu options are displayed (start flow).
- It can also be triggered at any point of the conversation when the bot user types a sentence that matches with the [intent](https://docs.yellow.ai/docs/platform_concepts/studio/train/intents) - ```Locate nearby clinics```
2. **Collect location:** User location is collected using the [location](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#24-location) node. This information is stored in a variable named **location**.
3. **Nearby clinics:** A search happens in the [database node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/database-node) that contains the location details of all the clinics. A flash message 'Please wait while we fetch the nearest branch.' is displayed using the [text](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/message-nodes1/message-nodes) node before showning nearby clinics.
- If there is a clinic closer to the user location, the flow moves to the **success** branch.
- If there's no clinic in or closer to the user location, the flow moves to the **fallback** and conveys this in a [text node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/message-nodes1/message-nodes).
4. **Clinic details:** The success branch is connected to a [function node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/function-node) which executes the function **nearbyClinics** and stores the clinic details in the variable **fiveNearbyDealers**.
5. **Display the clinic details:** The [function node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/function-node) is then connected to a [variable node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/variables-node) which is connected to a [condition node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/logic-nodes#1-condition) and [text node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/message-nodes1/message-nodes). At this step, the list of clinics will be displayed to the end user.
---------------
### 1.5 Collect reports
1. **Start trigger:** This flow is triggered when the bot user selects the **Collect report** button when menu options are displayed.
It can also be triggered at any point of the conversation when the bot user types a sentence that matches the intent: "collect healthcare reports."
2. **Displays relavant options to collect report:** Shows the MRN and Phone number options to collect report using the [carousel](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#16-carousel) node.
3. **Identify the selected option and display details to collect report:** The selected option from the Carousel node is identified by the [condition node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/logic-nodes#1-condition).
- If MRN option is selected, [question](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#11-question) node is used to obtain the MRN number.
- [Database](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/database-node) node is used to fetch MRN.
- [Function](https://docs.yellow.ai/docs/platform_concepts/studio/build/code) - ```generateDynamicLink``` function is used to fetch the report from the ```record health``` database, which is stored in a [variable](https://docs.yellow.ai/docs/platform_concepts/studio/build/bot-variables)- ```test_report``` and it converts the report into PDF format.
- Similarly, if phone number option is selected, [phone number](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#13-phone) node is used to get the phone number of the patient.
- [Database](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/database-node) node is used to fetch phone number.
- [Function](https://docs.yellow.ai/docs/platform_concepts/studio/build/code) - ```generateDynamicLink``` function is used to fetch the report from the ```record health``` database, which is stored in a [variable](https://docs.yellow.ai/docs/platform_concepts/studio/build/bot-variables)- ```test_report``` and it converts the report into PDF format.
-------------
### 1.6 Connect with support
[Prompt nodes](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes) are used to fetch the bot user's information such as ```phone number```, ```name```, and ```query```. These details are stored in the [respective variables](https://docs.yellow.ai/docs/platform_concepts/studio/build/bot-variables#31-create-a-variable-via-nodes) and passed into the [Raise ticket](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/raise-ticket) action node, this will connect the user to the support agent.
> Inbox must be set up to connect the bot user to a live support agent. A support agent must be available (online) when the support request is raised. Click [here](https://docs.yellow.ai/docs/platform_concepts/inbox) to learn about Inbox.
#### :pushpin: Tips
- Add/ Delete the number of FAQs listed on the Quick reply node.
- Add [FAQs](https://docs.yellow.ai/docs/platform_concepts/studio/train/add-faqs) based on your industry.
- **Name** and **Query** are the mandatory fields to use a **Raise ticket** node. You can reduce the prompt nodes to avoid collecting details from the users prior or you can add more prompt nodes to collect other details before connecting to the agent.
- As per requirements, you can fetch user details (name, email address, number) using **Prompt** nodes even if the user selects FAQs. This data can be used later for acquisition or monitoring purposes.
---
## SaaS template
> Explore **SaaS template** [here](https://cloud.yellow.ai/marketplace/78e7ad81f4a59ba097c5968ed08959e4).
Software as a service (or SaaS) is an industry concept of delivering applications over the internet. Marketplace's SaaS template is designed to promote an industry's SaaS products to customers and offer them a product demo.
Along with an option to explore products and offerings, customers can also view case studies of how this product was implemented to renowned customers and how it benefited them (customer testimonials). Customer can also book a product demo with a company executive and chat with live support agents.
You can customize this template as per your industry and business requirements. Reuse this flow design for your platform offerings (SaaS products), and add your customer use cases.
**Template use case**
This template is built around the use case to help customers explore the products provided by yellow.ai. One can learn about the platform offerings based on the descriptions of custom use cases, channels (like WhatsApp, or Instagram), or industries(government, private sector). These flows are built to promote products and urge the user to book a demo.
Bot users can also read customer use cases from the main flow, directly book a demo, or talk to an agent.
:::info
For details on importing and editing the markerplace templates, click [here](https://docs.yellow.ai/docs/platform_concepts/get_started/marketplaceintro).
:::
------
## 1. Prebuilt use cases
The most common use cases (flows) are prebuilt in this template for a SaaS industry to promote their products, following are the flows:
1. **Home flow/Display menu**: After the welcome message is displayed, WelcomeLCsXc is executed. It is the home flow that is designed for WhatsApp and other channels. It displays the menu a bot user can select as soon as the bot starts conversing.
2. **Explore products and offerings**: This flow is designed to provide insights into the available products. Based on the user's choice, the flow will switch to the respective product flow (explore by use case/channel/industry).
- **Explore by (use case, channel, and industry)**: These flows are cloned flows. They are all designed to display a description of the product and prompt the bot users to book a demo.
3. **Customer case studies**: This flow is designed to give a brief description of the company and its impact on the industries. It allows the bot user to select and explore the use cases implemented for a list of industries and read their testimonials. A pre-recorded demo/images can be displayed as a promotion and finally, the bot user will be prompted to book a demo.
4. **Book a demo**: This flow collects the bot user's details(name, number, email) and displays a calendar and clock to select a preferred time and date to schedule a call with the executive to understand the product in depth.
5. **Connect with support**: This flow provides customer support either by fetching answers from the trained FAQs or by connecting the bot user directly to the support agent after collecting the details (name, number, query).
These flows are explained in detail in the further sections.
:::note
The start trigger is a starting point at which the flow gets triggered(or executed). A flow can get triggered when a particular intent/entity/event/URL is identified or a flow can get triggered when [Execute flow](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/execute-flow) node is used in other flows. Click [here](https://docs.yellow.ai/docs/platform_concepts/studio/build/Flows/configureflow#configure-start-trigger) to learn more.
:::
---
### 1.1 Display the main menu
1. **Start trigger**: Immediately after displaying the welcome message, WelcomeLCsXc is triggered.
- At the end of each flow there is an option to go back to the main menu, when the *Main menu* button is clicked, WelcomeLCsXc is expected to be triggered.
- It can also be triggered at any point of the conversation when the bot user types a sentence that matches the intent- *Main menu* options. You can customize this [intent.](https://docs.yellow.ai/docs/platform_concepts/studio/train/intents#11-zero-shot-model)
2. **Identify the channel**: A logic node ([channel filter](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/logic-nodes#2-channel-filter) is used to identify the channel in which the bot conversation is happening. Nodes used in the further flow will be based on the channel.
3. **Quick reply buttons to display menu options**: For WhatsApp channel, [WhatsApp list](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#22-whatsapp-list) node is used to display the 4 menu options. Similarly, for other channels, [Quick reply](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#14-quick-replies) node is used to display the 4 menu options (Explore products and offerings, Customer case studies, Book a demo, and Connect with support).
#### :pushpin: Tips
- You can add [multiple channels](https://docs.yellow.ai/docs/platform_concepts/channelConfiguration/overview) to your bot, to reach the users through any mode.
- If you have varied products/menu options, you can add (or delete) the quick reply buttons and customize what can be displayed in the main menu.
---
### 1.2 Explore products and offerings
1. **Start trigger**: This flow is triggered when the bot user selects Explore products and offerings button when menu options are displayed.
- It can also be triggered at any point of the conversation when the bot user types a sentence that matches with the intent- *Products and offers* options. You can customize this [intent.](https://docs.yellow.ai/docs/platform_concepts/studio/train/intents#11-zero-shot-model)
2. **Display categories of products**: With a [carousel](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#16-carousel) node, 3 product categories are displayed.
3. **Verify product selection and execute the next flow**: After the bot user selects an option from the carousel node, the response (which is a trained entity value) is identified for the category using an if-else logic ([condition node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/logic-nodes#1-condition) and the respective flow for the selected category is executed by using [Execute flow](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/execute-flow) node.
- ```Explore_products``` is an [entity](https://docs.yellow.ai/docs/platform_concepts/studio/train/entities) which is trained for 3 categories of ```entity value``` (explore by use case, channel, and industry). The response obtained by clicking the carousel button will be identified as an entity value.
- If ```entity value``` is equal to ```Explore by use case```- **Explore by use case** flow will get executed.
- Else, if ```entity value``` is equal to ```Explore by channel```- **Explore by channel** flow will get executed.
- Else, if ```entity value``` is equal to ```Explore by industry```- **Explore by industry** flow will get executed.
- If none of the options are selected, a text will be displayed ([text node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/message-nodes1/message-nodes) asking the bot user to retry.
#### :pushpin: Tips
- You can add more details about your product using a text node before displaying a carousel node.
- You can add text, images, and more product category buttons to the carousel node.
- If you add new products, train those entity values on the [entity](https://docs.yellow.ai/docs/platform_concepts/studio/train/entities) section. Edit @explore_products and add a new list of product entity values.
- If none of the if-else conditions(categories) are selected, you can connect the last else condition to the **Execute flow** node and execute book a demo/connect to an agent or any of your custom flows.
-----
### 1.3 Explore by use case, channel or industry
> Explore by use case, Explore by channel and Explore by industry flows are designed in the same fashion to provide details about the respective category. Only the information(text/images) varies. This flow is explained by using Explore by channel as an example.
1. **Start trigger**: This flow is triggered when the category is selected in the **Explore products and offerings** flow.
2. **Display sub-categories**: Using a [carousel node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#16-carousel), sub-categories (Channels: Voice, Instagram, WhatsApp) are displayed.
3. **Verify the selected category and display details**: ```Explore_by_channel``` is an [entity](https://docs.yellow.ai/docs/platform_concepts/studio/train/entities) which is trained for 3 categories of ```entity value``` (Voice, Instagram, WhatsApp). The response obtained by clicking the carousel button will be identified as an entity value. If ```entity value``` is equal to ```Voice automation```, voice related details are displayed using Text, Video, and Image nodes. Similarly, when Instagram/WhatsApp are identified, the respective details are displayed.
4. **Next action**: After learning about the product, the bot user can select what to do next- two options (Book a demo and Main menu) are displayed using the [carousel](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#16-carousel) node. Book a demo or WelcomeLCsXc flow is executed next based on the response.
#### :pushpin: Tips
- Display varied number of sub categories by adding(or deleting) new buttons to step 1 (carousel node). Update the newly added values in @explore_by_channel on the entities page.
- Use other [message nodes](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/message-nodes1/message-nodes) like files or carousel to display product details.
- Next action carousel node can also have options to connect to an agent or any of your custom flows.
------
### 1.4 Case studies
1. **Start trigger**: Triggered when the **Customer case studies** option is selected from the main menu (WelcomeLCsXc).
- It can also be triggered when the bot user types a sentence that matches the intent- *customer case studies* options. You can customize this [intent.]
2. **Display an intro and sub-categories**: Using a [text node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/message-nodes1/message-nodes), details about the company are displayed followed by a carousel node to allow the bot user to select a category that they would like to learn more about (banking, retail, and government).
3. **Verify the category selected**: The selected category from the carousel is identified using a [condition node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/logic-nodes#1-condition).
- ```@case_studies``` entity is trained to identify case studies categories as ```entity values```.
- If ```entity value``` is equal to ```Retail``` the flow continues to show details pretaining to Retail. Likewise for the other categories.
> After selecting a category, the flow can be further designed to help the user understand the product, read case studies, watch demos, etc. This can be replicated for all the categories.
4. **Display introduction for the case study**: With [message nodes](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/message-nodes1/message-nodes) all the information related to the case study can be displayed. A **Text node** is used here.
5. **Identify channel and display quick replies**: Channel is identified using [channel filter](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/logic-nodes#2-channel-filter) node. If the bot user is conversing from a WhatsApp channel, [Carousel](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#16-carousel) node is used to display the 3 menu options. Similarly, for other channels, [Quick reply](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#14-quick-replies) node is used to display the 3 menu options (Read more, See bot in action, Go back).
6. **Identify the selected option and display details**: [Condition node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/logic-nodes#1-condition) is used to identify the selected options.
- If **Read more** is selected, Text node is used to display the detailed case study.
- If **See bot in action** is selected, an image node/ video node is used to display demo.
- If **Go back** is selected, the flow goes back to the previous node. This is configured in the [Tools section > Behaviour > Go back alias](https://docs.yellow.ai/docs/platform_concepts/studio/tools#221-behaviour).
7. **Next action**: 2 options (Book a demo and Main menu) are displayed using a carousel node. Depending on the option selected, intent is identified and respective flows are executed.
#### :pushpin: Tips
- Use message nodes to display more details.
- Provide varied options to the bot users by adding/deleting buttons on the carousel/ quick reply nodes.
----------
### 1.5 Book a demo
1. **Start trigger**: This flow is triggered when the bot user selects **Book a demo** button when menu options are displayed.
- It can also be triggered at any point of the conversation when the bot user types a sentence that matches with the intent- *I want to book a demo* options. You can customize this [intent](https://docs.yellow.ai/docs/platform_concepts/studio/train/intents).
2. **Collect user details and identify the channel**: [Text nodes](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/message-nodes1/text-node) are used to create a conversational flow. [Name](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#12-name), [Email](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#15-email) and [Phone](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#13-phone) nodes are used to collect user details. [Channel filter](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/logic-nodes#2-channel-filter) (condition node) is used to identify the channel in which the user is conversing in, based on the channel, date and time are collected.
> Different methods(nodes) are used for different channels as the format to obtain the date and time in each channel is different.
3. **Schedule demo (obtain Date and Time) for WhatsApp channel**:
- Using [Question](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#11-question) node, the bot user is asked to enter the date in DD/MM/YYYY format.
- ```@demo_date``` [entity](https://docs.yellow.ai/docs/platform_concepts/studio/train/entities) is trained in the entities section for the pattern - ```([0-2][0-9]|(3)[0-1])(/)(((0)[0-9])|((1)[0-2]))(/)\d{4}```. Using [Condition](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/logic-nodes#1-condition) node, it is verified if the user entered the date in DD/MM/YYYY format.
- If the date entered is correct, the date value is stored in a [variable](https://docs.yellow.ai/docs/platform_concepts/studio/build/bot-variables) - **demoDate**.
- Using [Question](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#11-question) node, the bot user is asked to enter the time in HH:MM format.
- ```@demo_time``` [entity](https://docs.yellow.ai/docs/platform_concepts/studio/train/entities) is trained in the entities section for the pattern - ```([0-1]?[0-9]|2[0-3]):[0-5][0-9]```. Using [Condition](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/logic-nodes#1-condition) node, it is verified if the user has entered the date in HH:MM format.
- If the time entry is correct, the time value is stored in a [variable](https://docs.yellow.ai/docs/platform_concepts/studio/build/bot-variables) - **demoTime**.
- **getCalenderTime** is a [function](https://docs.yellow.ai/docs/platform_concepts/studio/build/code) that is written to return **start** and **end** date-time (each scheduled meeting lasts for 30 min). **demoDate** and **demoTime** variables are passed into getCalenderTime function, and the code will calculate and return the **start** and **end** date and time. This output is stored in **StartDateTime** variable.
4. **Schedule demo (obtain Date and Time) for other channels**: Using the [Date](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#21-date) node (**Single date picker** widget type for date and **Time picker** widget type for time), Date and Time are stored in 2 [variables](https://docs.yellow.ai/docs/platform_concepts/studio/build/bot-variables#31-create-a-variable-via-nodes) (Day and Timeslot). Day and Timeslot variables are passed into the getCalenderTime function.
- **getCalenderTime** is a [function](https://docs.yellow.ai/docs/platform_concepts/studio/build/code) that is written to return **start** and **end** date-time (each scheduled meeting lasts for 30 min). **Day** and **Timeslot** variables are passed into getCalenderTime function, the code will calculate and return the **start** and **end** date and time. This output is stored in **StartDateTime** variable.
5. **Create Google calender event**: [Google calender third party integration](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/google-calendar) is enabled from the **Integrations** section. The details obtained from the conversation are passed into the **Google calendar** node to schedule a meeting (Title, Description, Start and End time, and Host and guest email).
6. **Identify the channel and display options to Confirm or Reschedule booking**: After the meeting is scheduled successfully, using the [Condition](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/logic-nodes#2-channel-filter) node, the channel is identified. If the identified channel is WhatsApp, [Carousel](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#16-carousel) node is used to display options to **Reschedule/Confirm**. If the bot conversation is happening from other channels, the [Quick replies](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#14-quick-replies) node is used to display **Reschedule/Confirm** options.
- **Reschedule booking**: If Reschedule is selected, the flow is directed back to step#3 to schedule a meeting from the beginning.
- **Confirm booking**: If the booking is confirmed, using a [Database](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/database-node) node, meeting details(**name, email, phone, demodate and demotime**) are stored in ```book_a_demo``` table ([table](https://docs.yellow.ai/docs/platform_concepts/studio/database) and respective columns are existing with the name ```book_a_demo```)
#### :pushpin: Tips
- Date and time format can be edited by changing the pattern of the respective entities.
- Other integrations can be used to book a meeting.
- Collect required details using [Prompt](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes) nodes and store the data in variables.
---------
### 1.6 Connect with support
1. **Start trigger**: This flow is triggered when the user selects **Connect with support** quick action from the main menu (WelcomeLCsXc flow). This flow can also be triggered when the bot user's input matches with any of the sentences(utterances) trained for **Queries and concerns** [intent](https://docs.yellow.ai/docs/platform_concepts/studio/train/intents).
2. **Display and verify support options (Agent/FAQs)**: With a [carousel](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#16-carousel) node, two options (Chat with support and FAQs) are displayed. The type of support selected is identified using [condition node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/logic-nodes#1-condition). ```@queries_and_concerns``` entity is trained to identify FAQs and Chat with support as ```entity values```.
- If the FAQs option is selected, answers to the user queries will be fetched from the trained FAQs.
- If Chat with support is selected, a support agent will be connected to take the conversation forward.
3. **FAQs**: All the FAQs about the company are added and trained with the answers in the [FAQs section](https://docs.yellow.ai/docs/platform_concepts/studio/train/add-faqs). When FAQs is selected, a condition node ([channel filter](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/logic-nodes#2-channel-filter) is added to identify the channel from which the conversation is taking place.
- If the conversation is happening on WhatsApp, [WhatsApp list](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#22-whatsapp-list) node is used to display the list of FAQs.
- If the conversation is via other channels, [Quick reply](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#14-quick-replies) node is used to display the list of FAQs.
- User can also type the query in the input bar.
- Based on the selection/entry, the answer will be fetched from the trained FAQs.
4. **Chat with support**: [Prompt nodes](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes) are used to fetch the bot user's information such as **phone number**, **name** and **query**. These details are stored in the [respective variables](https://docs.yellow.ai/docs/platform_concepts/studio/build/bot-variables#31-create-a-variable-via-nodes) and passed into the [Raise ticket](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/raise-ticket) action node, this will connect the user to the support agent.
> Inbox must be set up to connect the bot user to a live support agent. A support agent must be available (online) when the support request is raised. Click [here](https://docs.yellow.ai/docs/platform_concepts/inbox) to learn about Inbox.
#### :pushpin: Tips
- Add/ Delete the number of FAQs listed on the Quick reply node.
- Add [FAQs](https://docs.yellow.ai/docs/platform_concepts/studio/train/add-faqs) based on your industry.
- **Name** and **Query** are the mandatory fields to use a **Raise ticket** node. You can reduce the prompt nodes to avoid collecting details from the users prior or you can add more prompt nodes to collect other details before connecting to the agent.
- You can fetch user details using **Prompt** nodes even if the user selects FAQs. This data can be used later for acquisition or monitoring purposes.
------
---
## Migration Guide
---
## Cloud Platform Not Loading
# Yellow\.ai Platform Not Loading – Troubleshooting Guide
If you're unable to access the Yellow\.ai platform, follow the steps below to identify and resolve the issue.
## ✅ Step 1: Perform Basic Troubleshooting
Start with the following checks to rule out common browser or network-related issues.
### 1. Clear Browser Cache and Cookies
* Clear the cache and cookies from your browser settings.
* Refresh and try reloading the Yellow\.ai platform.
### 2. Open in Incognito or Private Mode
* Launch a private/incognito window in your browser.
* Open the Yellow\.ai platform URL and check if it loads successfully.
### 3. Try a Different Browser
* Use an alternate browser (e.g., Chrome, Firefox, Safari, Edge).
* Observe if the platform loads in the new browser.
### 4. Switch Your Network
* Change your internet connection (e.g., from office Wi-Fi to mobile hotspot).
* Attempt to access the platform again.
### 5. Check Firewall or Network Restrictions
* Contact your IT administrator.
* Ensure that **Yellow\.ai IPs and domains are whitelisted** in your firewall or proxy settings.
---
## 🛠️ Step 2: Still Not Working? Contact Yellow\.ai Support
If the issue persists after completing the steps above, please email **[support@yellow.ai](mailto:support@yellow.ai)** with the following details to help us investigate:
**Basic Information**
* **Bot ID**:
(You can find this in your platform settings or [click here](https://tinyurl.com/4sfeyrv4) for help.)
* **Issue Start Time**:
When did you first notice the problem? (Include date and time.)
* **Scope of Impact**:
Is the issue affecting only you, or are other users experiencing it as well?
**✅ Troubleshooting Checklist**
| Step | Tried? (Yes/No) | Observations |
| ---------------------------------------- | --------------- | ----------------------------------- |
| Cleared cache and cookies | | What happened after retrying? |
| Opened in incognito/private mode | | Was there any change in behavior? |
| Tried a different browser | | Which browser? What was the result? |
| Switched to a different network | | Any difference? |
| Confirmed Yellow\.ai IPs are whitelisted | | Has your IT team reviewed this? |
**📎 Screenshots and Error Messages**
* If available, attach any screenshots or console error messages to your email.
* These will help us diagnose the issue faster.
---
---
## Create AI agent for a sample use cases
This guide walks you through the process of designing and configuring the Yellow Travels AI Agent step by step. It is designed for first-time users to build and deploy their own AI agent.
---
## Yellow travels AI Agent use case
In this guide, we are considering the Yellow Travels use case to demonstrate how an AI Agent can be built and configured on the Yellow.ai platform.
Yellow Travels AI Agent is a conversational assistant built on the Yellow.ai platform to help customers with their travel needs. It automates flight bookings, hotel bookings, cancellations, and refund queries. It also allows handoff to live agents when required.
### Sample scenarios of Yellow travels
| Agent | Description | Example Conversation |
|-------|-------------|-----------------------|
| **Book a flight ticket** | Collects passenger details, trip info (departure, destination, date), generates a booking ID, and stores details in the database. | I want to book a flight from Delhi to Mumbai on 22nd Sept. | Stores details in travelDB and sends confirmation. |
| **Cancel a flight ticket** | Asks for booking ID, verifies it, and updates cancellation status. | Cancel my flight with Booking ID 12345. |
| **Book a hotel room** | Captures hotel stay details (location, check-in/out date, guest info), confirms booking, and captures data. | Book a hotel in Goa from 1st to 3rd Oct for 2 guests. |
| **Check refund status** | Takes the booking ID, checks refund progress, and informs user. | What's the refund status for Booking ID 12345? |
---
## How to configure AI agent
### Step 1: Configure Super agent
The Super Agent acts as the master controller for your AI Agent. It defines the persona, rules, and fallback behavior that apply across conversations.
1. [Create your AI agent](https://docs.yellow.ai/docs/platform_concepts/get_started/createfirstbot) based on your use case.
2. Go to **Super agent**.
3. [Review and edit](https://docs.yellow.ai/docs/platform_concepts/AIAgent/agentpersona#update-profile-settings) the following details (these attributes are cloned from the chosen template but editable anytime):
| Attribute | Description | Example |
|-----------|-------------|---------|
| Name | Enter the name of the super agent | Yellow Travels Bot |
| Persona | Defines agent’s tone and behavior | Friendly travel assistant |
| Role | Purpose of the agent | Help users book, cancel, and manage travel |
| Scope | Boundaries of what the agent can and cannot do | Handles only travel-related tasks |
| Model | LLM powering the responses | GPT-powered model (default template) |
4. Define the [welcome flow](https://docs.yellow.ai/docs/platform_concepts/AIAgent/agentpersona#define-welcome-message).
Example:
*"Hi, I’m Yellow Travels Bot! I can help you book flights, cancel bookings, or check refund status. What would you like to do today?"*
5. Add **conversation rules** (optional). Example:
- Always respond within 50 words.
- Follow step-by-step guidance.
6. Configure [Fallback behavior](https://docs.yellow.ai/docs/platform_concepts/AIAgent/agentpersona#how-to-handle-unanswered-queries) and [Live agent](https://docs.yellow.ai/docs/platform_concepts/AIAgent/transfer-live-agent) transfer.
---
### Step 2: Create individual Agents
Create one agent per use case:
- Flight ticket booking agent
- Cancel booking agent
[**Configure Agent documentation →**](https://docs.yellow.ai/docs/platform_concepts/AIAgent/agent#create-an-agent)
---
### Step 3: Configure Start trigger
Set how conversations should begin for each agent.
**Example triggers for Flight Booking:**
- "I want to book a flight"
- "Help me book a flight"
- "Book a ticket for my trip"
[**Start trigger documentation →**](https://docs.yellow.ai/docs/platform_concepts/AIAgent/agent#start-trigger)
---
### Step 4: Build Prompt — step-by-step
Prompts guide the conversation by collecting user input, validating it, and performing actions.
**Sample sequence for booking a flight:**
1. Collect user details:
- `getInput: full_name`
- `getInput: mail_ID`
- `getInput: phone_number`
2. Collect trip details:
- `getInput: departure_city`
- `getInput: departure_destination`
- `getInput: dateOfTravel`
3. Generate booking ID and store details:
- Generate random bookingID.
- `callWorkflow: travelDB` (pass collected variables).
4. Send confirmation message:
*Thanks `{full_name}!` Your flight from `{departure_city}` to `{departure_destination}` on `{dateOfTravel}` is booked. Booking ID: `{bookingID}`. We emailed the details to `{mail_ID}`.*
**Map prompts to actions:**
* Use [Get input](https://docs.yellow.ai/docs/platform_concepts/AIAgent/get-input) to capture user responses.
* Use Validation (built-in or custom) to validate email/phone/date.
* Use [Set variable](https://docs.yellow.ai/docs/platform_concepts/AIAgent/aigent-variables) to store temporary values.
* Use [Call workflow](https://docs.yellow.ai/docs/platform_concepts/AIAgent/call-workflow) fetch details to database, call payment, generate booking ID, call external APIs.
* Use [Dynamic rich media](https://docs.yellow.ai/docs/platform_concepts/AIAgent/get-input#dynamic-rich-media) (cards/carousel) to show flight/hotel options fetched from an API.
* Use [Transfer to Live agent](https://docs.yellow.ai/docs/platform_concepts/AIAgent/transfer-live-agent) action when the agent cannot resolve the issue or the user asks for human help.
---
### Step 5: Preview & Test
- [Agent builder preview](https://docs.yellow.ai/docs/platform_concepts/AIAgent/manage-conversation#preview-via-agent-builder)
- [Copilot simulation](https://docs.yellow.ai/docs/platform_concepts/AIAgent/manage-conversation#ai-copilot)
- [Preview on channel](https://docs.yellow.ai/docs/platform_concepts/AIAgent/manage-conversation#preview-agent-on-a-connected-channel)
**Testing:**
- Manual testing with [Copilot](https://docs.yellow.ai/docs/platform_concepts/AICopilot/copilot).
- Automated [Test suites](https://docs.yellow.ai/docs/platform_concepts/AIAgent/automated-agent-testing#scenario-based-testing).
**What to check in tests**:
- Input parsing.
- DB entries.
- Confirmation messages.
- Fallback.
- Live agent handoff.
---
### Step 6: Publish AI agent
After successful testing, click **Publish** on the Agent page.
---
## Build your bot conversation flow
After [creating your bot](https://docs.yellow.ai/docs/platform_concepts/studio/build/create_chatbot#create-chatbot-manually), you can begin building its flow to manage how it interacts with users. Flow creation includes the following steps:
* [Setup flow triggers](#setup-flow-triggers)
* [Create bot flows](#create-bot-flows)
* [Preview and test the bot](#preview-and-test-the-bot)
* [Publish the bot](#publish-the-bot)
## Setup flow triggers
Before building a flow, you need to create Intents and Utterances and train the bot to recognize them. This setup ensures that the bot can trigger the correct flows and respond appropriately.
### Create Intent and Utterances:
An Intent is what the user wants to achieve, like "booking a ticket".
Utterances are the different ways a user might express that intent. For example, "I need to reserve a ticket", "Book a flight ticket for me", and "I want to book a ticket". For more detailed information on how to create Intents and Utterances, click [here](https://docs.yellow.ai/docs/platform_concepts/studio/train/intents#add-intents-and-uttrances).
#### Prerequisite
Consider the following when creating Intents and Utterances:
* **Environment**: You should add intents or utterances only in a low-tier environment like **Sandbox** or **Development**.
**Intent naming best practices**:
* Minimum number of characters for an intent name: 10
* Minimum number of words: 10 (and unique)
* Special characters or numbers: Not allowed
* Duplicate intent names: Not allowed
### Add auto-generated utterances
The platform can auto-generate utterances that are based on the intent you added. This helps the bot understand and respond to the different ways users might phrase the same request. For more details, click [here](https://docs.yellow.ai/docs/platform_concepts/studio/train/intents#add-auto-generated-utterances).
### Train Intent and Utterances
You need to train your bot after adding intents and utterances. If the bot is not trained with the intent, it will not understand user queries and display a [fallback](https://docs.yellow.ai/docs/platform_concepts/studio/build/Flows/manage-flows#fallback-flow) response. For multiple languages, you need to train the intents and utterances in multilingual and not Sentence encoder. For more detailed information, click [here](https://docs.yellow.ai/docs/platform_concepts/studio/train/intents#train-your-bot-with-intents-and-utterances).
### Verify intent confidence
For a bot to accurately trigger the desired flow, you need to verify the confidence level of the added intent. This involves checking whether the intent's confidence score aligns with the user's input, ensuring the correct flow is initiated. The expected minimum confidence score is `0.85`. For more detailed information, click [here](https://docs.yellow.ai/docs/platform_concepts/studio/train/intents#test-your-intents).
## Create bot flows
Once you have created Intents and Utterances, you can start building your bot's conversational flow. This involves connecting different nodes that represent the steps of the conversation. There are several ways to create a flow:
* Create with AI Copilot
* Create from template
* Start from scratch
:::note
* You can add up to 150 nodes in a flow.
* There is no limit to create the number of flows in a bot.
:::
### Start node
The start node is an entry point for a bot to begin a conversation with the user. You can define a trigger point for a flow by selecting Intents, Entities, Event, or Page URL. Multiple trigger types can be added for a single flow. For detailed instructions, see [how to configure each trigger type](https://docs.yellow.ai/docs/platform_concepts/studio/build/Flows/configureflow).
### Connecting nodes
In the flow, each node represents a step. Start by clicking the starting point and connecting the appropriate nodes based on your use case.
## Preview and test the bot
After creating the flow, you can preview and test how the bot will appear, function, and interact with users.
## Publish the bot
After testing the flow, you can [publish](https://docs.yellow.ai/docs/platform_concepts/studio/test-and-publish-bot/modes) the bot to make it accessible to end users.
When you are publishing the changes from Sandbox to Staging, you do not need approver permission to approve it. But when you are publishing from Staging to Production, you need approver's permission. Only the super admin of the bot can approve the publish request.
### Cancel publish request
If you wish to make changes to the current flow or bot, or if you have raised a publish request by mistake, you can cancel the publish request.
---
## Debug issues using logs
This guide outlines the importance of reading logs for debugging issues on our platform, distinguishing between Execution Logs and Audit Logs.
### Prerequisites for accessing Debug logs
Before you begin, ensure the following:
* You have access to the platform’s developer tools.
* You hold the necessary permissions to view log entries.
* You are familiar with common log formats and error messages.
### Key objectives when reading Debug logs
Effective debugging requires interpreting logs for multiple purposes, including:
* **Identify the controller state**: Understand the current status and behavior of the system controller.
* **Determine the active flow**: Pinpoint which flow was triggered during the interaction.
* **Trace execution steps**: Follow each function’s execution path to uncover how the logic flows.
* **Inspect stored variables**: Review the values assigned to key variables throughout the process.
* **Detect errors**: Locate specific errors that may be disrupting the flow.
* **Analyze API activity**: Examine API calls, including response bodies and status codes, to ensure external services are responding as expected.
---
## Types of logs on our platform
Our platform provides two types of logs to assist in debugging:
1. **[Execution logs](#execution-logs)**: These logs help identify API failures that disrupt flows. They offer a detailed, step-by-step account of each flow's execution, making it easier to pinpoint issues.
2. **[Audit logs](#view--download-ai-agent-audit-logs)**: These logs store all operations performed on the platform, such as database deletions, journey deletions, and audience table deletions for audit purposes.
### Execution Logs
**Using execution logs to identify errors:**
* **Use the UID to identify errors**: To troubleshoot issues more precisely, use the UID (Unique Identifier) to trace errors. You can fetch the UID of any conversation transcript from the network tab API. To do this on the Live bot page, **right click** > **Inspect** > **Network** > **Payload**.
* **Additional methods for viewing logs**: There are advanced methods available to access and review logs, which provide deeper insights into the bot's operations and help identify critical issues.
To read the logs, follow these steps:
1. Go to **Automation** > **Analysis** > **Conversation logs**.
2. Go to the conversation log.
3. Click on **Logs**.
4. Click **Debugger** icon to get the logs for any user input and see what happened in the bot after that particular input.
5. To flag a conversation, click the flag icon corresponding to each conversation logs, or select the log and click **Filters** > **Flagged conversations** > **Flagged** > **Apply filter**.
* After flagging, you can revisit the conversation on the current or next day by searching for flagged conversations in the filter.
* In the **Logs** section, you can also view triggered events in any conversation. For example, if a "callbackStatus" event is triggered, click the **Debugger** icon, then click on the event to see details about the data the bot receives and the actions it takes after the event.
---
### Audit logs
#### View & download AI agent audit logs
Audit log provide a detailed record of the changes made to each module(APIs, Inbox Agent configuration/actions, Channels), including information about the user (user email) who made the changes and the timestamp of the actions taken.
To view audit log, follow these steps:
1. Click **AI agent settings** > **Audit logs** to access the log of all the changes made.
You will see the audit logs page with the details of all actions performed on the platform.
2. To filter the results and view specific information, you can use the **filter** button and apply relevant filters.
3. **To download a complete record of the Audit log, click on** **Download CSV**. This will provide a detailed history of all changes made to the AI agent over time.
:::note
Audit logs will be available for 6 months.
:::
---
## Disable callout banner
You can remove or disable the callout banner in the website AI-agent by triggering a specific event using the Send event node in your flow.
**Use case**
The callout banner is used to display promotions or important messages to users. If you want to remove the banner based on user actions or AI agent logic, you can use a Send event node.
## Configuration steps
### Step 1: Add a Send event node
In your AI agent flow, add a Send Event node at the point where you want to remove or disable the callout banner.
### Step 2: Configure the Event name in Send event node
In the Event name field, type the event name `ui-event-close-promotion`.
When the AI agent reaches this node during a conversation, the above event gets triggered and automatically the callout banner will be removed or disabled from the AI agent.
---
## Download API logs of the last 15 days
When there is an API issue, we don’t know if our API calls are failing or if the client API is failing. To resolve this issue we are now storing all the API requests and responses which will help establish the issues.
**How to use this log data?**
- There are multiple issues arising out of API failures. In these cases, we are not aware if calls from our platform are failing or if there are issues with customers' API only. You can download the data in this case and see some past requests and responses to establish what is the actual root cause.
- If the date and time of an incident of failure are known, then you can select the respective date and download the data. In the downloaded data search for the respective time and check the requests and responses.
- For better readability you can use tools like **VS code**, **jupyter notebook** etc.
## 1. API Logs data
API logs data stores all the API data like requests, responses, etc. The data would be available for requests sent from the [API Node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/api-node) only.
API download data would contain this information:
* API Name
* API Requests
* API Response
* Requests Timestamp
* Status Code (Failed/Success)
* Userid
## 2. Download API Logs
Follow the given steps to download the API logs:
1. Open **Automation** > **API** tab.
2. Select the environment.
- Logs will be downloaded only for the selected environment. For example, if you have selected the dev environment it would download requests sent from the dev env only.
3. Select the API for which you want to download logs data.
4. Select the date for which you want to download the data and click **Download**. Downloaded data will be Plain Text. You can open it in any tool for better readability.
Timeframe for which logs data is available:
- Data is available from 21st October.
- Data is available for the last 15 days.
- You can select only one day at a time to download.
- Data is not real-time, there is a 1 hr delay (if a request has been made at 6 PM, this data would be available to be downloaded after 7 PM).
---
## Dynamically load the callout banner in chatbot
You can dynamically load the callout banner in the bot by updating the relevant data in the database. This allows for real-time changes and customization of the banner content based on specific needs.
Consider an e-commerce bot where you want to display promotional offers based on data in the database columns like date, start time, and end time. By configuring the database appropriately, the e-commerce bot will display and update promotional banners dynamically.
**Scenario**: For an e-commerce platform, display a Christmas promotion from December 20th to December 25th.
Sample database entries:
date | start_time | end_time |banner_data
-----|------------|----------|----------
20-12-2024 | 00:00 | 23:59 | "Christmas sale starts now! 30% Off!"
21-12-2024 | 00:00 | 23:59 | "Exclusive christmas offers!"
22-12-2024 | 00:00 | 23:59 | "Last minute christmas deals!"
23-12-2024 | 00:00 | 23:59 | "Hurry! Christmas sale ending soon!"
24-12-2024 | 00:00 | 23:59| "Christmas eve specials!"
25-12-2024 | 00:00 | 23:59 | "Merry Christmas! final day of sales!"
**Outcome**:
* On 20 December, the bot will display: "Christmas sale starts now! 30% Off!"
* On 21 December, the banner updates to: "Exclusive Christmas offers!"
* This process continues dynamically, displaying the relevant banner data until the end of 25 December.
If you do not want the banner to be displayed, you can set the entire Date in the DD-MM-YYYY format and modify the logic accordingly in the flow to work.
#### Prerequisite
To load the callout banner dynamically, consider the following prerequisites:
* **Database setup**: Create a database with the relevant columns based on the banner requirement. For more information, click [here](https://docs.yellow.ai/docs/platform_concepts/studio/database#create-database-table).
* Use [send event](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/send-event-node) node: Use this node to call the event `ui-event-update-promotion`. When this event is triggered, the bot fetches the details from the database and displays them in a callout banner format.
#### Loading callout banner dynamically
To load the callout banner dynamically, follow these steps:
1. Create a flow to trigger the event. For more information, click [here](https://docs.yellow.ai/docs/platform_concepts/studio/build/Flows/configureflow#trigger-flow-using-event).
2. Based on the date specified in the database it searches the info and passes the response to the send event node.
3. Inside the send event node configure the custom data.
Select the event type as **Custom** and inside the data field pass the below code as per your requirement.
Below is the sample code:
```javascript
{
"banners": [
{
"title": "{{{variables.dbbanner_data.records.0.banner_message}}}",
"options": [
{
"title": "Devrev",
"url":"{{{variables.dbbanner_data.records.0.banner_but1}}}"
},
{
"title": "Google",
"url": "{{{variables.dbbanner_data.records.0.banner_but2}}} "
}
],
"type": "text"
},
{
"type": "image",
"imageURL": "{{{variables.dbbanner_data.records.0.banner_image}}} ",
"linkType": "url",
"linkURL": "{{{variables.dbbanner_data.records.0.banner_urlimage}}} "
}
],
"bannerSettings": {
"state": "close",
"textOnMinimise": "Hello this is banner minimize text"
}
}
```
---
## How to create dynamic quick replies?
A **Fetch from** field is available in the quick replies node to add the code to generate dynamic quick replies.
1. Include a [function node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/function-node) and write the code to generate dynamic quick replies(you can also refer to the [sample code](#sample-snippet-to-generate-dynamic-quick-replies) below).
2. Store the response of that function node in a [variable](https://docs.yellow.ai/docs/platform_concepts/studio/build/bot-variables#21-custom-variables).
3. Use quick replies node to display this data by passing the variable in the **Fetch from** field(as shown below).
### Sample snippet to generate dynamic quick replies
```js
return new Promise(resolve => {
// Your logic goes here
let title = data.variables.carsData2;
let options = [];
for (let i = 0; i < title.length; i++) {
options.push({title : title[i].Mfr_CommonName, text:title[i].Mfr_Name});
}
let qrObject = {
"title": "Here are list of cars from JAPAN",
"options": options
};
console.log(qrObject,"qrObject");
resolve(qrObject);
});
```
### Convert API Responses to Arrays
To parse API responses and convert them into an array format, refer the following snippet.
```js
return new Promise(resolve => {
let apiResponse = ymLib.args.apiResponse; // fetch API response
let body;
if (apiResponse && apiResponse.body) {
body = JSON.parse(apiResponse.body) // parse API response and store it in body variable
}
console.log(body,"2w2w2w2w2")
let cars = body.Results
let carsInfo = []
for(let i=0;i< cars.length; i++)
{
if(cars[i].Country=="JAPAN"){
carsInfo.push({"Mfr_CommonName":cars[i].Mfr_CommonName,"Mfr_Name":cars[i].Mfr_Name}) // fetch PostOffice Name and store in postOfficeName array
}
}
resolve(carsInfo);
});
```
## Create dynamic WhatsApp list
To create dynamic WhatsApp list, you need follow the same procedure as dynamic quick replies.
Use the snippet below to generate a dynamic Whatsapp list:
```js
return new Promise(resolve => {
// Your logic goes here
let title = data.variables.carsData2;
let options = [];
for (let i = 0; i < title.length; i++) {
options.push({title : title[i].Mfr_CommonName, text:title[i].Mfr_Name});
}
let qrObject = {
title: 'Please select the relevant option from below',
optionText: 'Options',
options: [
{
options: options
}
]
}
console.log(qrObject,"qrObject");
resolve(qrObject);
});
```
---
## Error occurred in Cloud Platform
If you encounters an error page while using the Yellow.ai platform, follow the troubleshooting steps provided to resolve the issue.
##### Prerequisites to resolve the error
Ensure you have access to the Yellow.ai platform to follow the troubleshooting steps.
## Troubleshooting steps
### Method 1: Clear cookies and site data
Follow these steps to clear browser data and attempt resolving the issue:
1. Open your browser's settings.
2. Clear the cookies and site data.
3. Re-login to the Yellow.ai platform and check if the issue persists.
:::note
If the issue continues after clearing cookies, proceed to [Method 2](#method-2-re-invite-the-agentuser-to-the-platform).
:::
### Method 2: Re-invite the agent/user to the platform
If clearing cookies and site data does not resolve the issue, follow the steps below to re-invite the user to the platform:
1. Click on the **Settings** icon (the gear icon located at the bottom left corner of the platform).
2. Search for "Access control" in the search bar and click on the **Access controls** option.
3. In the search bar, type the email address or name of the user facing the issue.
4. Click on the below high-lighted option and select **Delete**.
:::note
Make a note of the user’s current access controls before deletion to ensure the same permissions are given upon re-inviting.
:::
5. Once deleted, reload the screen and re-invite the same user again by clicking on the **+ Invite user** button on the same page.
6. Enter the user's email address and assign the access controls as noted or previously given. Then, click on the **+ Invite user** button.
7. Once the invite is sent, ask the user to accept the invite and re-login to the Yellow.ai platform. This should resolve the error.
---
## How to hide the input field in quick replies node?
Quick reply options provide a convenient way for users to interact with an interface, especially on mobile devices or when time is limited. By hiding the input field while displaying quick reply options, users can more easily focus on available options and quickly select the one that best matches their intent. To hide the input field,
1. Go to the Quick replies node and click the **settings** icon on the right corner.
2. Enable **Hide Input** and click **Save**.
The input field will no longer be visible on the bot.
---
## How to display images based on different languages?
1. Click the **Language** button on the left tile and add the preferred languages using **+Add language**.
2. Create a [global variable](https://docs.yellow.ai/docs/platform_concepts/studio/build/bot-variables#21-custom-variables) for language.
3. Add a [variable node](https://docs.yellow.ai/docs/platform_concepts/studio/build/bot-variables#-1-variables), in **Name** include the global variable and in **Value** enter one of the preferred [language codes](https://docs.yellow.ai/docs/platform_concepts/studio/build/localization#supported-languages).
4. Add [Set language node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/set-language) and add the global variable here.
5. Add an [image node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/message-nodes1/message-nodes) and add an image to it. This image will be mapped to the language code you entered in step 3.
4. Click the **Language** button on the left tile again, and select the language you want to update. Navigate to the image node, and change the current image with the corresponding image for the selected language. Repeat this step for all the languages.
5. Set a language code in the variable node to display the respective image in the bot
---
## Multilingual bot
You can create multilingual bots in yellow.ai platform through which your bot can understand and respond to users in multiple languages. This can be useful in situations where a large number of users speak different languages and need assistance in their preferred language. Please follow the below-mentioned steps to set up one such bot.
1. Go to your flow and click **Language** on the left tile.
2. Click **Add language** to add the languages your bot should support.
3. Go to **Train** and click **Tools**.
4. Set **Auto detect language** to **Yes** under **CONVERSATION** and click **Save**. This will let your bot automatically detect the end-user's language and enable conversation in the same language.
5. Add a [Quick Replies node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/message-nodes1/message-nodes) to your flow and populate the Button values with language options.
6. Click **Configure buttons** on the same pop-up and populate the button values with respective language's [ISO codes](https://docs.yellow.ai/docs/platform_concepts/studio/build/localization#supported-languages). Click **Save all changes** when you're done.
7. Store all response to this quick replies node in a [variable](https://docs.yellow.ai/docs/platform_concepts/studio/build/bot-variables#31-create-a-variable-via-nodes).
8. Add a [set language node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/set-language) to the node that takes ISO input(quick replies in this case). Select the variable in which the previous reply is stored. This language will be permanently set (currently set 2 days of expiry), unless it is being changed by same action node only.
The conversation with the bot after this point will be in the selected language.
**Related articles**
* [Languages supported](https://docs.yellow.ai/docs/platform_concepts/studio/build/localization#supported-languages)
* [Multi-language support](https://docs.yellow.ai/docs/platform_concepts/studio/tools#213-multi-language)
* [Set language node in Flows](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/set-language)
* [Language Translation](https://docs.yellow.ai/docs/platform_concepts/studio/build/localization)
---
## Implement new card in Yellow AI cloud platform
Follow the steps below to use the **card type** option on the **carousel** node in your flow:
## 1. Add a new card to the flow
1. Create a Function and store the variables in the function node as an Array. Our cards utilize the data from this variable to dynamically display it on the UI. If your card data is not dynamic, you may skip this step and directly add the data in the card node for non-dynamic cases.
> Regarding the code to use in the function, refer to table Code and Card Mapping for the new card in the next section.
:::note
This step is optional if you do not want to use dynamic data.
:::
2. Add another node in the carousel.
- Delete the default carousel.
- Select fetch from the variables that have been set in step 1.
- Edit the carousel setting based on the new card type. To edit the card type to use, you can hover the cursor to the right side and then click it.
> Regarding the Card type to use, refer to Code and Card Mapping for the new card below.
## 2. Code and Card Mapping for New Card
### 2.1 Tracker card
**Card Type in Carousel**
**Display in chat**
:::note
This card type displays only one card at a time. If multiple entries are added to the array, only the first card will be displayed in the widget UI.
:::
**Code in Function**
```js
[
{
"title": "Track Order",
"statuses": [
"Ordered",
"Ready",
"Shipped",
"In City",
"Arrived"
],
"currentStatus": "Arrived",
"from": {
"Title": "Mumbai",
"Description": "12/12/2021"
},
"to": {
"Title": "Bengaluru",
"Description": "14/12/2021"
},
"assigneeDetails": {
"key": "Name",
"value": "Purush",
"image": "https://cdn.yellowmessenger.com/PQuTgjPG7NxY1611996274269.png"
},
"details": {
"Order ID": "#444-2445-2442-222",
"Delivey": "14/12/2021",
"Total": "₹ 1500"
},
"actions": {
"title": "View data",
"text": "View data"
}
}
]
```
### 2.2 List Card
**Card Type in Carousel**
**Display in chat**
**Code in Function**
```js
[
{
"title": "COVID-19 Queries",
"options": [
{
"title": "Domestic - Covid travel guidelines",
"text": "Domestic - Covid travel guidelines",
"url": "https://yellow.ai"
},
{
"title": "International - Travel guideliness",
"text": "International - Travel guideliness"
},
{
"title": "Mandatory web check in",
"text": "Mandatory web check in"
},
{
"title": "Fly safe and hassle-free",
"text": "Fly safe and hassle-free"
},
{
"title": "Interest on credit shell",
"text": "Interest on credit shell"
}
]
},
{
"title": "Flight COVID-19 Queries",
"options": [
{
"title": "Domestic - Covid travel guidelines",
"text": "Domestic - Covid travel guidelines"
},
{
"title": "International - Travel guideliness",
"text": "International - Travel guideliness"
},
{
"title": "Mandatory web check in",
"text": "Mandatory web check in"
},
{
"title": "Fly safe and hassle-free",
"text": "Fly safe and hassle-free"
},
{
"title": "Interest on credit shell",
"text": "Interest on credit shell"
}
]
}
]
```
### 2.3 Transaction status card
#### Transaction status card (Payment success)
**Card Type in Carousel**
****
**Display in chat**
**Code in Function**
```js
[{
"title": "Payment success",
"success": true,
"text": "Your payment was successful & your order has been placed.",
"value": 1500
}
]
```
#### Transaction status card (Payment failed)
**Card Type in Carousel**
****
**Display in chat**
**Code in Function**
```js
[
{
"title": "Payment failed",
"success": false,
"text": "Your payment was failed & your order is not placed.",
"value": 1500
}
]
```
### 2.4 Contact Card
**Card Type in Carousel**
****
**Display in chat**
**Code in Function**
```js
[
{
"title": "Contact Info",
"download": "https://cdn.yellowmessenger.com/KpvHzrKBodtw1648483057986.jpg",
"options": {
"image": "https://cdn.yellowmessenger.com/PQuTgjPG7NxY1611996274269.png",
"key": "Name",
"value": "Purush"
},
"actions": [
{
"title": "email",
"text": "purushottam.yadav@yellow.ai",
"icon_class": "ri-mail-fill",
"url":"mailto:sankalp.gupta@gmail.com"
},
{
"title": "Phone",
"text": "Phone",
"icon_class": "ri-phone-fill",
"url":"tel:9810272341"
},
{
"title": "whatsapp",
"text": "whatsapp",
"icon_class": "ri-whatsapp-fill",
"url":"whatsapp://send?phone=+919810272341"
}
]
}
]
```
### 2.5 Receipt card
**Card Type in Carousel**
****
**Display in chat**
**Code in Function**
```js
[
{
"title": "Fixed Deposit",
"titleHeader": {
"1234 5678 1234 5678": "Status: Active"
},
"options": [
{
"key": "FD Amount",
"value": "$1,20,000"
},
{
"key": "Rate of Interest",
"value": "8.2% (p.a)"
}
],
"action": {
"title" : "Submit"
}
},
{
"title": "Fixed Deposit",
"titleHeader": {
"253236": "Status: Maturing Soon"
},
"options": [
{
"key": "FD Amount",
"value": "$1,20,000"
},
{
"key": "Rate of Interest",
"value": "8.2% (p.a))"
}
],
"action": {
"title": "Submit"
}
},
{
"title": "Fixed Deposit",
"titleHeader": {
"253236": "Status: Matured"
},
"options": [
{
"key": "FD Amount",
"value": "$1,20,000"
},
{
"key": "Rate of Interest",
"value": "8.2% (p.a)"
}
],
"action": {
"title": "Submit"
}
}
]
```
### 2.6 PDF preview card
**Card Type in Carousel**
****
**Display in chat**
****
**Code in Function**
```
return new Promise(resolve => {
// Your logic goes here
// console.log(data.profile, "profile zuhud");
let arr = [];
let pdfcard = {
"title": "Lorem Ipsum",
"text" : "lorem ipsum dolor amet",
"image" : "https://cdn.yellowmessenger.com/q9f6PUO48xbV1617021384235.jpeg",
"actions": [{
"title": "Preview",
"preview": "http://www.africau.edu/images/default/sample.pdf",
// "feedback": JSON.stringify({filename:'pdf-test.pdf'}) //optional
}, {
"title": "Download",
"buttonDefault": "url",
//"analytics": "analytics",
"url": "http://www.africau.edu/images/default/sample.pdf",
// "postback": "post-back"
} ]
};
arr.push(pdfcard);
resolve(arr);
});
```
### 2.7 Multi select transaction card
**Display in chat**
**Code in Function**
```js
[
{
id: ‘1b23-0zdc’,
title: “Pertam Kedua Ketiga”,
type: “Debit”,
image: “https://cdn.yellowmessenger.com/boXfK6e5d6LK1675079020492.png”,
status: “Success”,
amount: 10000,
accountName: “DCA”,
currency: “IDR”,
time: “2022-09-12T00:00:00.000Z”,
accountNumber: `${cardId}`,
additionalInfo: [
“Transfer to bank”,
“Destination : BCA”
]
},
{
id: “23bc-123x”,
title: “Pertam Kedua Ketiga”,
type: “Debit”,
status: “Success”,
amount: 10000,
accountName: “DCA”,
currency: “IDR”,
time: “2022-09-12T00:00:00.000Z”,
accountNumber: “xxxx-5678”,
additionalInfo: [
“Transfer to bank”,
“Destination : BCA”
]
}
]
```
### 2.8 Product card
**Display in chat**
**Code in Function**
```js
[
{
"title": "New Apple iPhone 12 (128GB)",
"text": "The iPhone 12 and iPhone 12 mini are part of Apple's latest generation of smartphones, offering OLED displays, 5G connectivity, the A14 chip for better performance, improved cameras, and MagSafe, all in a new, squared-off design.",
"value": [
"₹ 80,900",
"₹ 82,900",
"You save ₹ 2,900"
],
"input": true,
"image": [
"https://cdn.yellowmessenger.com/ZglWKNRsESKb1623145034869.jpeg"
],
"titleHeader": {
"₹ 82,900": "You save ₹ 2,900"
},
"options": {
"key": "Description",
"value": "The iPhone 12 and iPhone 12 mini are part of Apple's latest generation of smartphones, offering OLED displays, 5G connectivity, the A14 chip for better performance, improved cameras, and MagSafe, all in a new, squared-off design."
},
"actions": [
{
"title": "Purchase",
"text": "Purchase"
},
{
"title": "Know More",
"text": "Know More"
},
{
"title": "More",
"text": "More"
},
{
"title": "Visit Site",
"url": "https://www.yellow.ai"
}
]
},
{
"title": "New Apple iPhone 12 (128GB)",
"text": "The iPhone 12 and iPhone 12 mini are part of Apple's latest generation of smartphones, offering OLED displays, 5G connectivity, the A14 chip for better performance, improved cameras, and MagSafe, all in a new, squared-off design.",
"value": [
"₹ 80,900",
"₹ 82,900",
"You save ₹ 2,900"
],
"input": true,
"image": [
"https://cdn.yellowmessenger.com/ZglWKNRsESKb1623145034869.jpeg"
],
"titleHeader": {
"₹ 82,900": "You save ₹ 2,900"
},
"options": {
"key": "Description",
"value": "The iPhone 12 and iPhone 12 mini are part of Apple's latest generation of smartphones, offering OLED displays, 5G connectivity, the A14 chip for better performance, improved cameras, and MagSafe, all in a new, squared-off design."
},
"actions": [
{
"title": "Purchase",
"text": "Purchase"
},
{
"title": "Know More",
"text": "Know More"
},
{
"title": "More",
"text": "More"
},
{
"title": "Visit Site",
"url": "https://www.yellow.ai"
}
]
}
]
```
### 2.9 Slider card
**Display in chat**
**Code in Function**
```js
[
{
"title": "Loan Amount",
"slider": {
"step": 1000000,
"min": 1000000,
"max": 25000000,
"val": 0,
"min_content": "10 L",
"max_content": "25 Cr"
}
}
]
```
### 2.10 Single select transaction card
**Display in chat**
**Code in Function**
```js
[
{
id: ‘1b23-0zdc’,
title: “Pertam Kedua Ketiga”,
type: “Debit”,
image: “https://cdn.yellowmessenger.com/boXfK6e5d6LK1675079020492.png”,
status: “Success”,
amount: 10000,
accountName: “DCA”,
currency: “IDR”,
time: “2022-09-12T00:00:00.000Z”,
accountNumber: `${cardId}`,
additionalInfo: [
“Transfer to bank”,
“Destination : BCA”
]
},
{
id: “23bc-123x”,
title: “Pertam Kedua Ketiga”,
type: “Debit”,
status: “Success”,
amount: 10000,
accountName: “DCA”,
currency: “IDR”,
time: “2022-09-12T00:00:00.000Z”,
accountNumber: “xxxx-5678”,
additionalInfo: [
“Transfer to bank”,
“Destination : BCA”
]
}
]
```
---
## How to trigger a flow when a user clicks on a quick reply option on Whatsapp?
This guide will provide instructions on how to activate flows upon clicking a quick reply WhatsApp button and how to monitor the number of clicks for each button.
1. Go to **Automation** > **Event** > **Engagement** > **quick_reply_event** > **Activate**.
2. Go to **Build** > **+ Create flow**.
3. Search for **Whatsapp template** and click **+ Use template**.
4. Once the template is downloaded, go to the flow **Template handling** and set the **Start trigger** as **quick_reply_event**. This flow will be triggered when a quick reply option is clicked.
5. To manage the actions of your buttons, click the **Condition node** and set values to your buttons.
6. The buttons can either be connected to an [Execute flow](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/execute-flow) node (which will trigger another flow if clicked) or connected to[ Message nodes](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/message-nodes1/message-nodes) to display a message.
Navigate to the **Database** section and click the **template_qr_clicks** table to review the data pertaining to the buttons that have been clicked.
---
## Intents, FAQs and Utterances automated testing
Instead of manually training and testing intents, utterances, and FAQs, you can auto-generate and test them in bulk. This automation allows you to quickly train the AI-agent on all changes at once, saving time and reducing errors.
The platform will then run a prediction test and display results based on the confidence level. If the confidence level is low, the result will be displayed as a fail.
This guide will walk you through the process of testing intents, FAQs, and utterances in bulk via import.
### Test intents
You can upload all intents along with their associated utterances to your AI-agent and test them collectively. With a single click, you can train the AI-agent on all the changes at once. Based on the imported entities, the platform will then run a prediction test and display results based on the confidence level.
To test the intents, follow these steps:
1. Go to **Automation** > **Test**.
* You will see the following options. Choose your preferred options to test your AI-agent:
* [Import Intents](#import-intents)
* [Upload Utterances](#upload-utterances)
### Import Intents
1. Click the highlighted option below to import the entities from the Train section.
2. Click **Sync and test intents** to test intents that are out of sync with the Train section.
* This action will import intents from the Train section.
3. Choose the intent you want to test.
4. In the Utterances field, type any utterance and click **Generate utterances**.
* A list of utterances will be generated.
5. Select the utterances that you need to test and click **+ Add utterances**.
6. Click **Test intent**.
* The platform will run a prediction test and display results based on the confidence level. If the confidence level is low, the status of the utterance is displayed as fail.
7. To test other intents, click the back arrow (on the top left next to the intent's name) and click **Test intents**.
* This will test the utterances for all intents and display their status.
8. Click the **Download Report** button to download the tested utterances and access them offline.
The downloaded report includes the following details:
* **Utterance** - Utterances generated for the intents.
* **Intent** - Intents that will be triggered by those utterances.
* **predictedIntent** - The intent that was triggered for that utterance.
* **predictedConfidence** - The percentage at which the respective intent gets triggered.
* **Result** - Outcome of the predictions - **success** for successful predictions, **fail** for failed predictions.
### Upload Utterances
You can upload a list of test utterances and test it.
To upload utterances, follow these steps:
1. Click **Import entities** drop-down and select **Upload utterances**.
2. Click the **Download icon** to download the template.
3. Fill in the template with the following details:
* **Utterance**: The utterance for your intent.
* **Journey**: The journey or flow associated with the utterances.
* **Tag**: Labels that help recognize or filter important journeys.
4. Click the **Upload file** button to upload your template.
5. Download the report from the **Reports** section to check the status of the uploaded utterances.
The report includes the following details:
* **Utterance**: The utterances that were uploaded.
* **Predicted Journey**: The journey to which the utterances were mapped.
* **Journey**: The journey specified in the uploaded template.
* **Status**: Indicates success or failure, based on the correct mapping of the utterance to the journey.
## Test FAQs
To test FAQs, follow these steps:
1. Click **Test FAQ** > below-highlighted icon to import the FAQs from train section.
2. Click **Sync and test FAQs**.
* This action will import FAQs from the **Train** section.
3. Click on any FAQ.
4. In the variations field, type any question or text and click **Generate variations**.
* A list of variations will be generated.
3. Select the variations you need to test and click **+ Add variations**.
* This will add the variations.
4. Click Test FAQ.
* The platform will run the prediction test and display results according to the confidence level. The result is pass if any utterance trigger has the same intent with high confidence, else it is fail.
4. To test other FAQs, click the back arrow (on the top left next to the FAQ's name) and click **Test FAQ**.
* This will test the FAQs and display their status.
8. Click the **Download Report** button to download the tested FAQs and access them offline.
The downloaded report includes the following details:
* **Utterance** - Utterances generated for the intents.
* **Intent** - Intents that will be triggered by those utterances.
* **predictedIntent** - The intent that was triggered for that utterance.
* **predictedConfidence** - The percentage at which the respective intent gets triggered.
* **Result** - Outcome of the predictions - **success** for successful predictions, **fail** for failed predictions.
## Test KB
You can add a list of FAQs and upload it to generate answers based on the document uploaded in the KB section. Note that duplicate questions cannot be created and the answers will not be generated for them.
#### Limitations of KB bulk testing
When performing KB bulk testing, you need to consider the below limitations to prevent bulk tests from exceeding token or request limits and to ensure optimal performance for live bot traffic:
* **Bulk test limit**: You can only run 3 bulk tests per day.
* **Query limit per report**: Each bulk test report can include a maximum of 500 queries.
:::note
If you need to run a bulk test with a larger dataset, contact [customer success team](mailto:customersuccess@yellow.ai) with the relevant details for further evaluation.
:::
To upload KB FAQs, follow these steps:
1. Choose Sandbox/Development environment.
2. Go to **Knowledge base**.
3. Click **+ Add URL**. Add your website URL and click Save.
4. Go to **Automation** > **Test** > **Test KB**.
4. Click the download icon to download the template.
5. Fill in the template with the following detail:
* **Questions**: Enter the question for which you want to generate the answer.
6. Click **Upload questions** button to upload your template.
* A report is generated with a percentage of answered questions.
7. Download the report from the **Reports** section to check the status of the uploaded FAQs.
The report includes the following details:
* **Questions**: The questions that were uploaded.
* **Answers**: The answers are generated for the uploaded questions.
* **Links**: Generates the links from where the answers are fetched from the uploaded document.
---
## How do I retrieve Database data inside a bot flow?
1. [Insert a Database node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/database-node) in your flow.
2. In the Database node, set the **Select type** as **Search**, select the table that contains the details and set the filter based on which the search action should be performed.
3. Click the **Select Variable** option at the bottom right corner and create a new variable. All the information in your database will now be stored in this variable. Use this code snippet `**{{{variables.dbResponse.records.0.fieldName}}}**` in your flows to retrieve a specific set of data.
---
## Functions & API related use cases
# Store API response in a variable
## How to store API response values as objects in your bot
In this tutorial, you will learn how to store all the values from an **API** (Application Programming Interface) response as an object. This allows you to use the data effectively across different nodes of your bot. By following the steps mentioned below, you can easily manage and utilize API data throughout your bot’s features.
## What is an API response?
An API response is the data that you receive from an API when you request information. This data can include various details, like names, addresses, and other relevant information. Storing this response as an object helps you access the data easily.
---
## Steps to store API response
### Step 1: Define the response object
You will begin by defining what the response from the API looks like. This is done by creating a response object. Consider the code provided below:
```javascript
// Define an object to store key information about a school
const response = {
"school": "School Name", // Name of the school (string)
"address": { // Address of the school (object)
"street": "2nd Main", // Street address
"doorNo": "23/1", // Door number
"city": "New Delhi" // City of the school
},
"city": "Anytown", // City where the school is located (string)
"state": "CA", // State abbreviation (string)
"zip code": "91234" // Postal code (string)
};
```
### Explanation:
**Purpose:**
In the code snippet provided above, we created an object called response that holds both string values (like the school name, city, state, etc.) and a nested object (the address of the school).
**Components:**
- **Constant variable:**
`const response` establishes a constant variable that holds the API response.
- **Object structure:**
The curly braces `{ }` define an object, which is a way to group related information.
- **key-value pairs:**
Each piece of information is represented as a key (like `"school"`) paired with its corresponding value (like `"School Name"`). We also have an object inside another object for the "address" key. This structure allows for easy access and management of the data.
## Step 2: Access values from the Object
In this step, you will learn how to access and use specific values from the API response object. The following code snippet demonstrates this process:
```javascript
return new Promise(resolve => {
const { apiResponse } = ymLib.args; // Extract the API response
let { body } = apiResponse; // Retrieve the body of the response
body = JSON.parse(body); // Parse the body into a JavaScript object
console.log(body, "API response in test"); // Log the response for debugging
// Access string value (school name)
let { school } = body;
// Access nested object properties (address details)
let { address: { street, doorNo, city } } = body;
resolve({ school, street, doorNo, city }); // Resolve the promise with the desired values
});
```
### Explanation:
#### Purpose:
This code snippet retrieves and manages data from an API response. It shows how to access both string values (like the school name) and nested object properties (like address details).
#### Components:
- **Promise creation:**
`return new Promise(resolve => { ... })` initiates an asynchronous operation to handle the API response while the rest of your code continues executing.
- **API response extraction:**
`const { apiResponse } = ymLib.args;` extracts the API response from `ymLib.args`.
- **Body retrieval and parsing:**
`let { body } = apiResponse;` retrieves the main content of the response, and `body = JSON.parse(body);` converts it into a JavaScript object.
- **Accessing string value:**
`let { school } = body;` extracts the school name
- **Accessing object properties:**
`let { address: { street, doorNo, city } } = body;` retrieves the street, door number, and city from the nested `address` object.
- **Promise resolution:**
`resolve({ school, street, doorNo, city });` resolves the promise with the extracted values for further use.
### Accessing variables
1. **For string variables**: To access and display a string variable (e.g., `school`), use:
`{{{variables.school}}}`
2. **For object variables**: If the variable is an object, access its properties using dot notation. For example, to get the `street` property from the nested `address` object, use:
`{{{variables.school.address.street}}}`
:::note
* You can use the `console.log()` function to check the value of the variable in the logs. This will help you to debug the issue.
* If you are debugging an API call and you are not seeing the data that you expect, it is possible that the response is missing a body. In this case, you will need to parse the response body in order to access the data.
:::
**Checklist**
1. **Verify API call success**: Make sure that the API call is successful. You can check this by inspecting the response in the developer tools.
2. **Check variable assignment**: Confirm that the API response is correctly stored in the relevant variable. You can check this by inspecting the variable in the developer tools.
3. **Ensure proper parsing**: If working with a response object, verify that it is parsed properly to access the desired data. You can check this by inspecting the response object in the developer tools.
---
## How to capture the ticket assigned event?
**Use case:** After creating a ticket and assigning to an agent, we need to invoke an API based on the response stored in the **Raise a Ticket** node.
Use ```ticket-assigned-bot event``` event for this. To activate this event:
1. Store the response of the [Raise Ticket node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/raise-ticket) in a variable.
2. Call the following API from your backend.
```
curl --location 'https://cloud.yellow.ai/api/agents/settings/ticketUpdateEventSettings?bot=x1599195792555' \
--header 'X-API-key: ' \
--header 'Content-Type: application/json' \
--data '{
"chatAssignedBot": true
}'
```
This is a one-time process. After that, you'll start receiving **ticket-assigned-bot** events, which you can activate in the **Custom Event** section and [use it in your flows](https://docs.yellow.ai/docs/platform_concepts/studio/build/Flows/configureflow#trigger-flow-using-event). For steps to create a custom function, click [here](https://docs.yellow.ai/docs/platform_concepts/studio/events/event-hub#custom-events).
---
## How to trigger a specific bot flow
To trigger a specific flow when there are multiple flows in the bot, you can use the flow slug.
A slug is a combination of the flow name and auto-generated characters in the following format: `/{flow_name}_{auto_generated_characters}`
To trigger a specific bot flow, follow these steps:
1. Go to **Automation** > **Build** > **Flows**.
2. Navigate to your preferred flow from the **Flows** drop-down.
3. Copy the flow path from the URL after *flow/*.
4. Click **Preview** and then open the bot preview page in a new tab using the icon highlighted below.
5. Clear the browser cache before you preview the bot. It is recommended to use Incognito mode or Private window to preview flows
6. In the address bar, append the following:
**To append after the base URL**:
`?ym.triggerJourney={journey_slug}`
>
> Example: https://cloud.yellow.ai/liveBot/x1635319612954`?ym.triggerJourney=feedbackflow_wwgpfq`
**To append it after a variable**:
`&ym.triggerJourney={journey_slug}`
> Example: https://cloud.yellow.ai/liveBot/x1635319612954?region=&ym.triggerJourney=feedbackflow_wwgpfq
---
## How to trigger a flow when a user clicks on a Whatsapp Template response?
1. Create your WhatsApp templates in the **Engage** module by following the steps mentioned [here](https://docs.yellow.ai/docs/platform_concepts/engagement/outbound/templates/whatsapptemplate).
2. Go to the Whatsapp template manager [here](https://cloud.yellow.ai/marketplace?name=whatsapp%20template).
3. Click the template to open it and click **+Use template**.
4. Select the bot in which you want to use the template, and click **Use template**.
5. Go to the flow **Template handling** and select the **Condition** node.
6. Populate the contains/equal to fields with the names of the respective WhatsApp template.
7. Then, go to each of the flows and populate the equal to fields with the button names in the respective WhatsApp templates.
8. Once you have populated the template names and the button names in the condition nodes, the respective flow gets triggered when a user clicks on a response.
---
## Function use cases
---
This guide introduces you to different ways of using **Functions** in **Automation**. It shows you how to automate tasks within your bot in a simple and easy way. By exploring practical examples and clear explanations, you'll learn how to use Functions to streamline your bot’s capabilities.
---
## 1. Display weather information in a carousel node
### Objective
Show real-time weather data within a carousel format in your bot interface.
### Steps to implement
#### 1.1. Add the weather API
[Add the Weather API](https://docs.yellow.ai/docs/platform_concepts/studio/api/add-api#1-add-a-new-api-using-url) to your bot platform to enable it to retrieve weather information.
#### 1.2. Create a flow and add the API node
Next, [create a flow](https://docs.yellow.ai/docs/platform_concepts/studio/build/Flows/journeys#2-create-a-flow) and insert an [API node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/api-node). Use this node to call the Weather API and fetch real-time data.
#### 1.3. Store the API response
Store the API response in an object variable so that you can extract required information easily using functions.
#### 1.4. Write a function to format the response
Navigate to the **Functions** section and write a function to process the saved API response. Ensure that the response is formatted to match the dynamic structure required for a carousel display. For more details on dynaamic carousel formatting, refer [here](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/message-nodes1/carousel-message-node).
### 1.5. Include a function node
1. Add a [Function Node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/function-node) in the flow.
2. Choose the function you created.
3. Store the response in your preferred variable and mention its datatype (e.g., object, string, etc.) for clarity.
### 1.6. Populate the Carousel Node
1. Insert a [Carousel Node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/message-nodes1/message-nodes) in the flow.
2. In the **Fetch from** field, select the variable with the formatted weather data.
3. Display the data in the carousel format.
:::note
**Alternate Method**: You can directly pass the function into the **Parse API response** field if you prefer not to use the Function Node.
:::
---
## 2. Calculate a date 45 days before today
### Objective
Compute a date that is 45 days before the current date and display it in the bot.
### Steps to implement
#### 2.1. Create a flow and define a variable node
[Create a new flow](https://docs.yellow.ai/docs/platform_concepts/studio/build/Flows/journeys#2-create-a-flow) and add a [variable node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/variables-node). Define a variable - **bookingDate** and assign it the value `{{{date.timestamp}}}` , which captures the current date and time.
#### 2.2. Display the captured date
Insert a [Text Node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/message-nodes1/message-nodes) and display the **bookingDate** value to verify that the current date has been captured correctly.
#### 2.3. Write a function to calculate the new date
Now, create a function that processes the timestamp and subtracts 45 days from the current date.
```javascript
return new Promise(resolve => {
// Retrieve the current booking date from the variables
let bookingDate = data.variables.bookingDate;
// Convert the booking date string into a Date object
let dt = new Date(bookingDate);
// Subtract 45 days from the current date
dt.setDate(dt.getDate() - 45);
// Format the new date to a localized string
let pdate = dt.toLocaleString();
// Split the formatted date string to isolate the date components
const myArraydate = pdate.split(",");
// Further split the date component to extract day, month, and year
const myArray = myArraydate[0].split("/");
// Construct a new date string in the desired format (MM/DD/YYYY)
let newDate = myArray[1] + "/" + myArray[0] + "/" + myArray[2];
// Update the bookingDate variable with the newly formatted date
data.variables.bookingDate = newDate;
// Resolve the promise with the new date string
resolve(newDate);
});
```
#### 2.4. Display the computed date
Insert another [Text Node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/message-nodes1/message-nodes) to display the date that was calculated (45 days before the current date). Use the variable containing the new date.
### Example output
Once the flow runs, the bot will display the result to the user like this:
---
## 3. Code snippet for sentence autocompletion
This code helps your bot suggest sentence completions based on user input. When the user starts typing, the bot looks for matches within its existing data and provides suggestions.
```javascript
return new Promise(resolve => {
console.log("inside autoSuggestion");
let result = data.variables.autoComponents;
const { term } = data;
let suggestions = [];
result.forEach((hit) => {
if (hit.component.toLowerCase().includes(term.toLowerCase())) {
suggestions.push([hit.component, hit.component]);
}
});
resolve(suggestions);
});
```
## 4. Code snippet for BASE64 decoding
Base64 encoding represents data using 64 ASCII characters. When an encrypted string is received via an API, we decrypt it to obtain the original object. After decoding, the file can be uploaded to a server, such as Yellow's server. Here's an example that demonstrates decoding, uploading, and sharing the file URL.
```javascript
// Execute an API call and wait for the response
let call_api = await app.executeApi('api_name', { argument: _value });
// Parse the JSON response from the API call
let api_data = JSON.parse(call_api.body);
// Log the API data for debugging or tracking purposes
app.log(api_data, "#####API DATA");
// Decode the base64-encoded file from the API response
let buffer = new Buffer.from(api_data.obj_name, "base64");
// Upload the decoded file to the Yellow.ai server and get the file URL
let file_url = await app.uploadFile(buffer, 'File.pdf'); // 'File.pdf' is the name of the uploaded file
// Optional: Uncomment the line below to send the file as a document to the user
// await app.sendDocument(file_url, { caption: "FILE", filename: 'File.pdf', mime: 'application/pdf' });
// Create and send a card with a download link for the uploaded file
await app.sendCards([
{
title: "Kindly download the same as PDF", // Title of the card
actions: [{
title: "DOWNLOAD", // Action button title
url: file_url // URL for downloading the file
}]
}
]);
```
---
## Handling User inactivity events
**User Inactivity Events** help manage conversations when users stop responding. You can use them to follow up, repeat prompts, or even redirect the conversation automatically—ensuring conversations remain active and productive.
To know how to configure User inactivity event, see [here](https://docs.yellow.ai/docs/platform_concepts/studio/events/event-hub#-user-inactivity-event).
### Common use cases
1. **Send a Reminder Message to the User**
Gently re-engage users who have gone silent.
2. **Nudge Users to Respond to the Previous Prompt**
Remind the user and repeat the last unanswered question.
3. **Trigger a Flow (e.g., Feedback or Survey)**
Automatically redirect the user to another flow after inactivity.
---
### How to set up inactivity events
#### 1. **Send a reminder message**
1. Go to **Automation > Events**, then click **User Inactivity Events**.
2. Click **+ Add Event**, provide an event name, description, and delay (recommended: 5+ minutes).
3. Enable the **Handle event with message** toggle.
4. Enter the reminder message (e.g., *“You haven’t responded in a while. Need help?”*).
5. Save the event.
#### 2. **Send a reminder and repeat the last prompt**
1. Follow steps in **Use Case 1** above.
2. Additionally, select the **Show previous prompt** checkbox.
This will re-display the previous question along with the reminder message.
#### 3. **Trigger a flow on inactivity**
1. Go to **Automation > Events > User Inactivity Events**.
2. Create a new event and set a delay (e.g., 5 minutes).
**Do not** enable the **Handle event with message** toggle.
3. Save the event.
4. Open the flow you want to trigger. On the **Start Node**, choose:
* **Event** as the trigger type.
* Select the **User Inactivity Event** you just created.
This setup ensures the new flow is triggered automatically when the user is inactive.
### Advanced configuration options
| Option | Description |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| **Activate for specific steps** | Limits the inactivity event to selected flows and steps only, giving you granular control over when the event should trigger. |
| **Handle event with message** | If enabled, allows sending a reminder message and optionally repeating the last prompt. If disabled, use it to trigger other flows instead. |
| **Allow context switching** | Lets users break out of the current conversation and start a new one, helping them switch context smoothly. |
:::note
This event gets triggered for the specific node in a flow only if the user has been previously responding in the flow. If the user does not respond at all from the beginning of the flow, this event will not get activated.
:::
---
## Chat disconnecting at the customer level
In some use cases, clients may want users to have the ability to disconnect from a chat without agent intervention. This process outlines the steps for enabling user-initiated chat disconnection.
:::info
To make chat disconnection accessible at the customer level, Display a banner to users, guiding them to type `talk to bot` or click a button on the banner if they want to return to the bot. This interaction will enable customers to disconnect from the chat independently.
:::
## Steps to configure user-initiated chat disconnection
1. **Enable custom events**: Enable the custom events `ui-event-update-promotion` and `ui-event-close-promotion` in the bot settings.
2. **Trigger the banner on agent connection**: When a live agent ticket is raised, use the `ui-event-close-promotion` event to display a banner with the following configuration.
Banner message with text input:
```
{
"title": "Do you want to exit from chat? Please type 'talk to bot'",
"options": []
}
```
Banner message with button input:
```
{
"title": "Do you want to exit from chat?",
"options": [
{
"title": "Exit",
"text": "talk to bot"
}
]
}
```
3. **Send the event**: Use the Send Event node to trigger the `ui-event-close-promotion` event with the configured banner. This banner should now be visible to the customer, allowing them to disconnect the chat on their own.
4. **Train the bot with an intent**: Train the bot with utterances like `talk to bot` and link the intent to the desired journey to enable a smooth transition back to the bot.
5. **Enable bot-triggered journey**: Once the customer clicks the banner button or types the designated phrase, the bot will initiate the assigned journey. Subsequently, the `ui-event-close-promotion` event can be triggered to close the banner.
6. **Close the ticket**: Use the ticket close API to close the ticket accordingly.
:::note
- Ensure the events are in the enabled state for them to trigger correctly.
- The object text should be consistent with what’s defined here for smooth functionality.
:::
---
## Webview
WebView enables you to add custom UI elements (using HTML, CSS, and JavaScript) into your chatbot. To use this feature, create your custom UI components with the necessary HTML code. Collaborate with the platform team to deploy your code on Yellow's Bitbucket repository. Once deployed, the platform team will host your code on Yellow's CDN, generating a unique URL. This URL can then be integrated into your chatbot's WebView node.
You can preview the WebView in the WebView node. However, if the URL is invalid or restricted due to Content Security Policy (CSP), please contact our support team for assistance.
:::note
Due to our website's CSP (Content Security Policy) guidelines, the Web View cannot be loaded on the bot's direct link. It can be accessed via the [PWA](https://docs.yellow.ai/docs/platform_concepts/channelConfiguration/pwa#access-the-pwa-link-for-your-ai-agent) link, a local HTML file, or when embedded on a website.
:::
### Prerequisite
* Before getting started, get the Webview node enabled for your bot. To enable the Webview node, contact [support team](mailto:support@yellow.ai).
## Steps to configure the Webview
### Step 1: Create HTML for custom Webview UI
Below is the sample code of the UI component:
```html
Mr Appliance
```
### Step 2: Host component on Yellow.ai's CDN
Host this component on Yellow.ai's CDN. A URL is generated.
Here's an example of the URL:
```html
https://app.yellowmessenger.com/components/webview/mr_appliance_llc/form
```
### Step 3: Configure Webview node
To configure the webview node, follow these steps:
1. Go to **Automation** > **Build** > **Flows**.
2. Search for the Web wiew node and select it.
3. **Enter URL** of the UI component hosted on Yellow.ai's CDN.
4. Specify the **Hieght** of the UI component based on your preference.
5. Enable **Hide input bar** to hide the input bar in the chatbot.
6. Enable **Hide home button** to hide the home button in the chatbot.
7. Enable **Scrollable** to make the UI component scrollable in the chatbot.
8. Enable **Full width** to view the UI component in a horizontal view in the chatbot.
9. Enable **Fixed position** to view the full view of the UI component in the chatbot.
10. Preview the bot to view the custom UI component in the chatbot.
---
## WhatsApp AI agent issues
This document outlines why your AI agent on WhatsApp may stop responding to certain users and provides clear steps to help you troubleshoot and resolve the issue.
The AI agent becomes unresponsive only for specific users on the WhatsApp channel. This issue is not caused by Yellow.ai’s platform. Yellow.ai relies on Meta's WhatsApp Business Cloud API to send and receive messages. If the AI agent does not respond to certain users, it indicates one of the following:
* Message delivery issues on Meta's infrastructure
* Temporary API delivery failures
* User-side network or device-related restrictions
### Steps to troubleshoot
1. **Perform initial self-check**
* Refer to Meta's official WhatsApp troubleshooting documentation:
[Meta WhatsApp cloud API support guide](https://developers.facebook.com/docs/whatsapp/cloud-api/support/)
* Check the following:
- Is the affected user online and receiving messages from other WhatsApp contacts?
- Has the user blocked the business number?
- Are other WhatsApp features (like media sharing or links) working for that user?
2. **Raise a ticket with meta**
If the issue continues and appears isolated to Meta's infrastructure, you need to raise a support ticket directly with [Meta](https://business.facebook.com/direct-support/).
3. **Contact Yellow.ai support**
If you are unable to reach out to Meta directly, contact [support](mailto:support@yellow.ai) with the following details:
Required details | Description
-----------------|------------
Problem summary | A brief explanation of what's not working
Start time & date | When the issue first occurred
Impacted WhatsApp Number(s) | Provide phone number(s) affected
Screenshots / Screen Recording | Visual evidence of the issue (if available)
Device details | Device model, OS version, browser if applicable
Support team will raise a Meta support ticket on your behalf and keep you updated as we receive information. As this issue originates from Meta's WhatsApp infrastructure, Yellow.ai cannot guarantee a resolution timeline.
Support team will provide status updates based on responses from the Meta support team.
---
## Introduction to outbound campaign for voice agents
An outbound campaign refers to a focused marketing strategy designed by businesses to actively communicate with customers or potential prospects. Through personalized messages delivered via different channels, businesses can aim to engage the audience and perform specific actions.
## Outbound campaign via. voice calls
- With Yellow.ai's **Engage** module's **Flow campaign**, you can leverage **voice agents** to deliver targeted messages, notifications, promotional offers to your customer base. By utilizing voice as a communication channel, you can create a more human-like and engaging campaign experience for your customers, driving higher response rates and enhancing customer satisfaction.
> Steps to set up an outbound campaign using voice agents on yellow.ai is covered in the next article.
### Flow campaign (campaign flow builder) for voice agents
* The **Flow campaign** enables you to create dynamic and intelligent workflows that adapt based on customer responses or behaviors.
* These flows can be designed to switch between different communication channels, such as voice calls, WhatsApp, SMS, and more, ensuring your messages reach customers through their preferred medium.
* This multi-channel approach enhances the effectiveness of your outbound campaigns and allows for higher customer engagement and conversion rates.
:::info
Click [here](https://docs.yellow.ai/docs/platform_concepts/engagement/flows_campaign) for the detailed guide to understand **Flow campaign**.
:::
### Target audience for flow campaign
* You can configure and automate your outbound campaigns by integrating with your existing customer data through [User360](https://docs.yellow.ai/docs/platform_concepts/engagement/cdp/overview).
* You can target specific [segments](https://docs.yellow.ai/docs/platform_concepts/engagement/cdp/user_data_segments/segments_overview) or individuals with relevant messages.
* Flows designed on Engage flow campaign are targeted towards the users on user360 (not to all the voice agent users).
-------
## Voice agent-driven outbound campaign use cases
A few examples of how voice agents can be used to send outbound campaigns:
1. **Appointment reminders**
* Collect customer appointment details and integrate them with your system.
* Design a voice agent flow that includes the appointment date, time, and any specific instructions.
* Schedule automated voice calls to customers prior to their appointments to remind them of the upcoming event.
* Provide an option for customers to confirm or reschedule their appointments through voice interactions.
2. **Order updates**
* Integrate your order management system with the voice agent platform to access real-time order information.
* Develop a voice agent script that informs customers about their order status, including processing, shipment, and delivery updates.
* Automate voice calls triggered by order status changes, keeping customers informed throughout the order fulfillment process.
* Provide options for customers to request additional information or make changes to their orders through voice interactions.
3. **Event invitations**
* Segment your target audience based on relevant criteria such as demographics, interests, or past event attendance.
* Create a personalized voice agent flow that delivers event details, highlights key speakers or sessions, and includes registration instructions.
* Schedule outbound voice calls to invite selected customers to the event, emphasizing the value and benefits of attending.
* Incorporate an option for customers to RSVP or inquire about event-related queries through voice interactions.
4. **Service notifications**
* Identify the types of service notifications that are relevant to your business, such as system updates, maintenance schedules, or subscription renewals.
* Develop a voice agent flow that conveys the necessary details, including the purpose of the notification and any actions required from the customer.
* Schedule automated voice calls or messages to proactively notify customers about service updates or upcoming renewals.
* Enable customers to interact with the voice agent for further information, confirmation, or assistance related to the service notification.
5. **Promotional offers**
* Define your target audience based on customer preferences, purchase history, or loyalty program participation.
* Craft a persuasive voice agent script that presents the promotional offer, highlights its benefits, and includes any relevant terms or conditions.
* Deploy outbound voice calls or messages to deliver the promotional offer directly to the targeted customers.
* Incorporate options for customers to redeem the offer, make a purchase, or receive more information through voice interactions.
---
## Set up outbound campaign via. yellow.ai voice agents
In this article, you will learn how to select an entry rule and design a campaign flow for voice agents.
:::info
**Prerequisite**
1. **User segmentation**: Grouping users based on shared characteristics, such as interests or behaviors, is known as user segmentation. There are two types of segments: static segments, which remain constant, and dynamic segments, which update automatically based on user data. To send targeted campaigns, you need to have user data grouped into segments in **user360**. Segments like product interest or recent purchasers can be created for effective messaging.
> Follow the steps provided [here](https://docs.yellow.ai/docs/platform_concepts/engagement/cdp/user_data_segments/segments_overview) to create and manage user segments
2. **Events**: an event refers to a recognized occurrence by the voice agent (asynchronous). In **Automation**, there are various events available, such as widget, inbox, engage, integration, user inactivity, schedule, User 360, and custom events, which are used to handle occurrences and perform tasks.
> Learn more about events and the steps to create custom events [here](https://docs.yellow.ai/docs/platform_concepts/studio/events/event-hub).
:::
To create a voice agent campaign, follow these steps:
## Step 1: Create a voice agent campaign workflow
1. Log in to your [yellow.ai](https://cloud.yellow.ai/) account. Open **Engage** > **Outbound**.
2. On the **Flows** tab, select **+Create workflow**.
------
## Step 2: Select entry rule for the voice agent campaign
To get started, follow the steps below:
1. Select the entry rule that best aligns with your business needs.
| Entry rule | Trigger |
| -------- | -------- |
| [User events](https://docs.yellow.ai/docs/platform_concepts/engagement/flows_campaign#user-events) | Select this to trigger the flow when a specific user event occurs. |
|[User entered a segment](https://docs.yellow.ai/docs/platform_concepts/engagement/flows_campaign#user-entered-a-segment) | Select this to trigger the campaign when the user enters a specific segment. |
|[User exited a segment](https://docs.yellow.ai/docs/platform_concepts/engagement/flows_campaign#user-exited-a-segment) | Select this to trigger the campaign when the user exits a specific segment. |
|[User present in a segment](https://docs.yellow.ai/docs/platform_concepts/engagement/flows_campaign#user-present-in-a-segment)| Select this to trigger the campaign only when the user is in a specific segment. |
2. **Choose your audience**: When selecting entry rules, you have the option to choose one or multiple user segments or target all users in User360.
3. **Set campaign schedule**: For each entry rule, you can determine the frequency and specific time for running the campaign.
-------
## Step 3: Add voice call node and configure the campaign
:::note
- Voice calls can only be added to the workflow if the voice agent has an IVR (Interactive Voice Response) configuration in place.
- It is necessary to configure a flow that the voice agent will follow when the campaign is triggered. This flow will serve as a template for voice calls.
- If you intend to use other message channels such as SMS or Email, you need to configure the senderID/channel and ensure that a corresponding template is available for that particular channel.
:::
To initiate a voice call, follow the steps below:
1. Connect the **Voice call node** (available under the message category) to the initial node in the workflow.
2. Enter the details.
- **Enable answering machine detection (AMD)** : You have the option to enable AMD, which helps determine if a voice call made by the agent is answered by a human or a machine (such as a voicemail system).
- **Bot flow**: From the dropdown menu, select the desired flow that should be triggered when the campaign call is made to customers. All available flows in Automation are listed here.
- **From**: Choose the IVR number(s) from which the voice call should be made. If multiple IVRs are added, the calls will be made randomly from any of those numbers.
- **To**: Select the variable that contains the user identifier. Click [here](https://docs.yellow.ai/docs/platform_concepts/engagement/cdp/user_data/userid-flow) for steps on setting up user identification.
- **Call trigger time**: Set the business hours in the **Settings** and configure the flow to be triggered only during those designated business hours.
3. Add connecting nodes to the voice node to determine the subsequent steps based on different scenarios. You can define the next actions based on whether AMD is detected, the call is answered, the line is busy, there is no answer, or if the call fails to connect.
:::note
You can add [conditions](https://docs.yellow.ai/docs/platform_concepts/engagement/flows_campaign#condition-to-trigger-flow-campaign), [flow control](https://docs.yellow.ai/docs/platform_concepts/engagement/flows_campaign#flow-control) and [action](https://docs.yellow.ai/docs/platform_concepts/engagement/flows_campaign#action) to design the flow.
:::
-------
## Step 4: Add goal to end the voice agent campaign
To prevent spamming users, it is recommended to add a campaign goal. When an event is detected that signifies the completion of the goal, users will exit the flow and the campaign will end.
Follow these steps to add a new goal to the flow:
1. Click **Add new goal to the flow**.
2. Add details:
- **Name**: Type any custom name.
- **Event**: Select an event that you have activated in Automation. When this [event](https://docs.yellow.ai/docs/platform_concepts/studio/events/event-hub) is identified, it will indicate that the goal has been reached.
- **Set goal validity**: Choose the duration for which the goal should remain valid. After the specified duration, the campaign will still be active, but the goal won't be considered.
3. **Save** the goal.
-----
## Step 5: Publish workflow for voice agent campaign
1. Click on **Publish** to publish the flow and make it active.
2. Once the campaign is published, it will automatically run for users who meet the entry rule criteria.
3. To monitor the status of the voice agent campaign, track the users who have entered the campaign, and keep a count of the number of times the goal has been achieved, refer to the flow campaign page.
---
## Testing Voice agents using WebRTC feature
Yellow.ai offers a **WebRTC (Web Real-Time Communication)** calling feature that enables browser-based calls directly from the platform. This allows bot developers to simulate and experience agent interactions with both Indian and international numbers—without the need to procure or map PSTN phone numbers.
By removing the dependency on external telephony systems, it significantly speeds up voice agent development and testing.
This feature is especially useful for testing voice agents and previewing their responses for customers outside India (e.g., in the US, UK, or UAE).
:::note
WebRTC testing is enabled by default at no cost for the following regions: **R0, R2, R3, R4, and R5**. To enable it for regions **R1, R6, or R7**, please contact the support team at [support@yellow.ai](mailto:support@yellow.ai).
:::
## Testing voice agent using WebRTC
:::info
WebRTC testing is only **available** in **Sandbox, Staging and Development** environments and not available in *Production/Live*.
:::
To test a voice agent using the WebRTC feature, follow these steps:
1. **Open the Preview Mode**
- Navigate to **Automation > Flows > Preview**.
- Select **Voice** from the dropdown.
> You cannot preview an individual flow for voice agents. When you click **Preview**, the entire agent is launched starting from the Welcome/Start flow. Switching between flows during the session will disconnect the call.
2. **Start the Call**
- Ensure microphone access is granted.
- Click the **Start Call** button to initiate the WebRTC-based call.
4. **Answer and Test**
- Interact with the voice agent to test various call flows and behaviors.
- Use the on-screen keypad to enter DTMF inputs, if required. WebRTC calls support DTMF INFO-based input transmission instead of audio tone detection.
- Click **Disconnect** once your testing is complete.
-------------
### Network monitoring & feedback
* If **internet connectivity** drops or either party disconnects, UI will display feedback indicating disconnection.
* If **packet loss or jitter** exceeds acceptable thresholds, visual warnings will be shown to notify the developer.
* When making calls to numbers in different regions, you may experience latency, with the Round Trip Time (**RTT**) displayed. However, RTT isn't a direct indicator of connection quality. For example, a call from Region 0 to a voice agent hosted in Region 4 might show around 300ms RTT, even with excellent connectivity.
---
### Agent transfer during testing
When testing a voice agent and the **agent transfer** flow is triggered, the call will remain active for up to **2 minutes** before being automatically terminated by the system.
> This 2-minute limit applies **only** when the call is transferred to a **human agent**. All other agent interactions are not subject to this timeout.
#### (Optional) Set a Caller Line Identity (CLI)
To display a test-friendly number (instead of the default voice agent number) when your call connects to a human agent during WebRTC testing, you can configure a **Caller Line Identity (CLI)**:
- Go to **Node > Settings > Channels > Voice**.
- In the **Caller Line Identity** field, enter the number you want to show as the caller ID.
- Click **Save**.
#### Before call disconnection, developers should validate
- The call is successfully transferred or assigned to a human agent.
- Relevant metadata (e.g., user’s email, name, or transcript) is correctly passed to the agent interface.
---
## Introduction to voice agent builder
:::note
To explore the voice features, you must create a **voice agent**.
Functionalities such as Design(for voice), Voice input node, etc. will not work for chat agent.
:::
## 1. Create a new voice agent
> If you are a new user, refer to [this](https://docs.yellow.ai/docs/platform_concepts/get_started/account-setup) article.
1. [Log in](https://cloud.yellow.ai) to your account and click **+Create new agent**.
2. Select **Create from scratch**.
3. Enter these details:
- **Subscription**: Select the **subscription** under which you want to create this agent.
- **Bot type**: Choose **Voice bot**.
- **Avatar**: Choose/upload an avatar (your agents display photo).
- **Industry**: Select from the dropdown.
- **Region**: Select from the dropdown.
- Select **Add live chat support to your agent** if you want to add a customer support flow.
4. Click **Create bot**.
--------
## 2. Methods to build a voice agent conversation
To convert your idea of a voice conversation (use-case) into a agent flow, there are three approaches:
1. Build a agent from scratch using **Voice input node**.
2. Import a **Marketplace template** to your agent and modify it to accommodate voice conversations.
> These methods are explained in further articles.
-------
## 3. Nodes supported for voice agents
Only the following [nodes](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes) can be used to build voice agent flows:
| Category | Nodes |
| ------------------- | ----------------------------------------- |
|Message|[Text](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/message-nodes1/message-nodes) |
| Prompts | [Voice input](https://docs.yellow.ai/docs/cookbooks/voice-as-channel/build/usingvoiceinput) , Call forwarding, Call disconnect [Speak](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-node-overview/speak-node), [Name](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-node-overview/name-node), [Phone Number](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-node-overview/phone-node), [Question](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-node-overview/question-node)|
| Logic | [Condition](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/logic-nodes#1-condition) |
| Action | [Set variables](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/variables-node), [Function](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/function-node), [Database](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/database-node), [API](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/api-node), [Execute Flow](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/execute-flow) |
## 4. Configure voice nodes/flows through settings
You can configure voice-related features like - Conversation language, Bot speed, User response capture duration, etc. for all the nodes used to build a flow for voice agents.
There are two methods to configure these voice options:
1. **Global options**: These settings will be applicable by default for all nodes/flows. For example **Conversation language** and **Speed** of the conversation will ideally be constant throughout the conversation.
> Learn more on configuring global options [here](https://docs.yellow.ai/docs/platform_concepts/studio/tools#25-voice)
2. **Node options** - Output of a few nodes demand to behave in a certain way, for this, the node level settings can be configured. This overrides global options for the nodes wherever it is defined. These settings can be different for each node. For example: **Capture response time** can be different while capturing the user's address (using the question node) vs. the user's phone number (using the phone node).
> Learn more on configuring node options [here](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes#32-configure-node-for-a-voice-bot)
---
## Using marketplace templates to build a voice bot
Coming soon!
---
## Using voice input nodes(prompt) to build a voice agent
The voice input node offers added features that enhance the performance of voice agents. Building voice agents using the "Voice input" node improves conversational experiences with a more natural and human-like interaction style.
- **Streamlined SSML handling**: Removes the necessity for manual SSML (Speech Synthesis Markup Language) coding.
- **Simplified validation process**: Integrates validation directly into the flow, eliminating the need for separate configuration.
- **Intent and Entity recognition**: Facilitates the identification of user intents and entities, enabling the voice agent to understand and respond appropriately to diverse user queries and requests.
- **Tracking of unidentified utterances**: Provides the ability to monitor and manage unidentified user utterances efficiently.
- **Collect PCI-Compliant Data Securely**: You can now mark input fields as PCI-compliant to securely collect sensitive cardholder information. When a field is designated as PCI, the platform automatically applies encryption, disables logging, and stores the data using secure protocols.
The following PCI data types are supported:
* Card number
* CVV (card security code)
* Card PIN
* Expiry date
-----
## Build a flow with voice input node
### Use-case
Consider building a Banking voice agent that asks users questions to identify them and resolve their queries. In this example, the voice agent guides the user through providing their name and phone number to inquire about an eligible home loan, receiving detailed responses.
> Let's break down the conversation:
> **Bot** (asks): What is your name?
> **User** (replies): Karan
> **Bot** (stores): Karan as Name
> **Bot** (asks): How may I help?
> **User** (replies): Loan eligibility
> **Bot** (understands): User request = Loan eligibility
> **Bot** (logic): Required phone number to calculate Loan eligibility
> **Bot** (asks): What is your phone number?
> **User** (replies): 9890******
> **Bot** (validates if the number is correct): Uses logic to calculate Loan eligibility
> **Bot** (response): You can avail X amount on X% interest.
--- End of the call ---
:::note
For guidelines to build a good conversation, click [here](https://docs.yellow.ai/docs/cookbooks/getting_started).
:::
----
### Steps to configure voice input node
#### Prerequisite
The Voice Input node will only work for voice agents, meaning you must have enabled **Voice agent** when creating your voice agent.
center>
#### Steps to configure
1. Go to **Automation** > **Prompts** > **Voice input**.
2. In **[Input type](#input-type)**, select the type of information you want to capture from the user through voice.
To securely **capture PCI-related details**, choose one of the supported types. The platform automatically encrypts PCI data and stores it securely with restricted access.
- PCI – Card number
- PCI – Card security code
- PCI – Card PIN or
- PCI – Card expiry to capture PCI-related details securely.
:::note
Responses will be stored in the respective PCI-protected variables.
:::
3. In **Bot speaks**, enter the message that the voice agent will say to request the user's phone number.
4. In **Repeat message**, input the message that the voice agent will repeat if the user's response is unclear or requires verification.
5. In **[Validator](#validator)**, validate the user input against the chosen criteria.
6. In **[Capturing the user input](#capturing-user-input)**, configure how the voice agent should gather user inputs.
7. In **[Additional settings](#additional-settings)**, adjust configurations to enhance conversation authenticity and emulate human-like interactions.
For PCI related inputs, you can Additional Settings to define how PCI data is passed to your API.
* **Encoding type**: Choose how the PCI input is encoded —`Text`, `Hexadecimal`, or `Base64`.
* **Card number format**: Choose the format in which users are expected to enter the card number. This helps validate and correctly capture card data.
* `XXXXXXX XXXXXX`
* `XXXX-XXXX-XXXX-XXXX`
* `XXXX XXXX XXXX XXXX`
:::note
Values updated in this node will override the global values.
:::
### Example: Configure node for phone number
Following are the steps to collect a **user's phone number** using the voice input node:
1. In the **Input type** section, choose the **Input type** as **Phone** and enter the messages for **Bot speaks** and **Repeat** **message** fields.
2. In the **Validator** section, choose **Phone** in the **How do you want to validate user input** drop-down and enter the **Failure message** and **No Response message**. Mention the **Boost Phrases** too.
3. In the **Capturing user input** section, choose **Voice** and **Keypad** in the **Capture input as** drop-down and fill in the rest of the fields.
4. [Store the response in a variable](https://docs.yellow.ai/docs/platform_concepts/studio/build/bot-variables#41-store-variables).
----
## Input type
| Field | Description |
| -------- | -------- |
| **Input type** |Choose the type of user response. 1.Name2.Email 3. Phone 4. Question 5. PCI – Card number6. PCI – Card security code7. PCI – Card PIN8. PCI – Card expiry |
|**Bot Speaks**|The voice agent's reply that will be vocalized to the end-user during a call. |
|**Repeat message**|The voice agent's reply that will be vocalized upon the user's request for the voice agent to reiterate the question or prompt. |
You can add multiple messages to all of the above mentioned options by [adding random messages ](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/message-nodes1/message-nodes). You can also play the message (SSML) to hear the voice agent response.
### PCI data masking in voice calls
You can also collect PCI-sensitive information, such as card number, CVV, PIN, or expiry date. When you select a PCI input type, the platform automatically encrypts the data, applies strict logging restrictions, and stores it securely. This data is never retained in logs or databases and can only be accessed securely through the API node.
Use Additional Settings to define how PCI data is passed to your API.
* **Encoding type**: Choose how the PCI input is encoded —`Text`, `Hexadecimal`, or `Base64`.
* **Card number format**: Choose the format in which users are expected to enter the card number. This helps validate and correctly capture card data.
* `XXXXXXX XXXXXX`
* `XXXX-XXXX-XXXX-XXXX`
* `XXXX XXXX XXXX XXXX`
-----
## Validator
### How do you want to validate user input
Choose the criteria against which the user input should be validated. 1. [Name](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#12-name) 2. [Phone](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#13-phone) 3. [Email](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#15-email) 4. [Intent](https://docs.yellow.ai/docs/platform_concepts/studio/train/intents) 5. [Entity](https://docs.yellow.ai/docs/platform_concepts/studio/train/entities) 6. [Regex](https://docs.yellow.ai/docs/platform_concepts/studio/train/entities#42-regex) 7. Intent and entity
:::note
You can choose several intents and entity or their combination in the validator. If the user's intention matches any of them, it will be validated, and the flow will move to the next node.
:::
### Failure Message
**Failure message** is vocalized when the validation fails.
- **+Add message**: Click this button to add up to three successive fallback responses when the voice agent encounters invalid response from the user.
### No response message
**No response message** is vocalized when there is no user response in the configured max response time.
- **+Add message**: Click this button to add up to three successive fallback responses when the voice agent gets no-response from the user.
:::note
You can add upto 3 Failure messages and No response messages each.
:::
### Boost phrases
Some user responses can be confusing for the voice agent to understand. Region specific words, new genz lingos, internet terminologies, trending phrases, abbreviations are trained specially so that the voice agent understands the exact intention. For example, COVID is a new term that has been used frequently, the phrase COVID must be boosted, otherwise it gets translated to kovind/ go we/ co-wid etc. Ex - you should add the phrases that you expect from the user response like, < I want to take covid vaccine >
-----
## Capturing user input
**Capture input as:**
You can capture the user response as:
- **Voice**: Capture only voice input.
- **Keypad**: Capture only input from the keyboard.
- **Voice and Keypad**: Capture input from both voice and keyboard.
### Voice
| Fields | Description |
| -------------------------- | ----------- |
| **STT engine** | Select an engine from the dropdown- Google/Microsoft. |
| **STT mode** | Select mode from the dropdown. Microsoft provides "Static", "Streaming" or "Streaming Advanced", "Streaming 2.0". Google provides "Static". |
| **STT language** | Speech-To-Text i.e. transcription language (or user language)(ISO code) can be selected from the dropdown. Click [Microsoft](https://learn.microsoft.com/en-us/azure/cognitive-services/speech-service/language-support?tabs=stt-tts) or [Google](https://cloud.google.com/speech-to-text/docs/languages) for more information on the languages)|
| **STT engine endpoint** | Optional endpoint of the STT custom model. |
| **Recording max duration** | This value is the Max duration for which the voice agent will wait after asking a question (in any step) even while the user is speaking. For example, after asking “Which city are you from?” and the recording duration value is “5" - the voice agent records only 5 seconds of user response. This option is necessary to avoid consuming unwanted information and to stay with the conversational flow. If the user mistakenly replies with long paragraphs when a question is asked or if the user's response is getting shadowed with constant background noises, the voice agent must not process those long inputs. Hence, with this configuration, the voice agent only takes the necessary response and can quickly process the user response. |
| **Recording silence duration** | This value is the Max duration for which the voice agent will wait after asking a question (in any step) for the user to respond. For example, if recording silence duration is 5 seconds, voice agent waits for 5 seconds for the response if the user is silent. If the user does not respond anything within 6 seconds, voice agent Message will be played. |
| **Initial silence duration** | To provide more customization on the silence duration parameter, “streaming” and “streaming-advanced” STT modes (of Microsoft STT engine) allow to specifically configure the maximum acceptable silence duration before the user starts speaking. For example, the acceptable initial silence duration for the application number question could be higher (~3/4 seconds) but in the case of a quick conversational binary question, it could be configured to 1 second. |
| **Final silence duration** | Similar to the initial silence duration, the final silence duration is indicative of the maximum duration of pause that the voice agent will wait for once the user has started speaking. For example, for binary/one-word questions like yes/no we could set the final silence duration to ~0.5/1.0 seconds and for address-like fields where taking a pause is intrinsic in conversation, we can set the final silence duration to ~1.5/2.5 seconds. |
### Keypad
|Field|Description|
|------|----------|
| **DTMF digital length** | Enter the length of characters to be captured. Ex: For an indian phone number, it is 10. |
| **DTMF finish character** | Character which defines when the voice agent must stop capturing. Supported finish characters - "*" and "#"|
### Voice and keypad
All the above mentioned options for **Voice** and **Keypad** will be listed together.
----
## Additional settings
| Fields | Description|
| -------- | -------- |
| **Enable wait message** | Enable this toggle to vocalize an acknowledgement message to the user awaiting a message from the voice agent. |
|**Wait message**| Acknowledgement message displayed to the user.|
|**Recording action**|With the recording management options, you can select to pause/resume/stop recording depending upon different use-cases and conversations. By default, the recording is ON. Once you STOP the recording (for recording sensitive dialogues), it can’t be resumed back.|
| **TTS engine** | Select the engines from the dropdown- Microsoft Azure, Google Wavenet, Amazon Polly. |
| **Text type** | Select Text/SSML from the dropdown. |
| **TTS language** | Bot Language(ISO code) can be selected from the dropdown.|
| **Pitch** | Pitch value can be any decimal value depending on the base of voice required, 0 is ideal. You can add this for Microsoft if text_type = "text" and for Google for text_type = "text" and "SSML". |
| **Voice ID** | Type the characters of voice ID. You can add this for Microsoft if text_type = "text" and for Google if text_type = "text" and "SSML". |
| **TTS Speed** | This value defines how fast the voice agent must converse. This value can be 0.9 - 1.5 for the voice agent to soundly humanly. You can add this for Microsoft if text_type = "text" and for Google if text_type = "text" and "SSML". |
-----
## Custom response
### Custom responses for each identified input
When the system is expecting an input from a user, it handles scenarios where the input doesn't align with expectations. In such cases, customized responses can be used to guide or assist the user.
Each input is treated as a condition within an if-else structure. Validators are utilized to define these conditions. For every validation or validator, the voice input node interprets it as a distinct if-else condition.
If the user's input matches one of the expected values defined by the validators, the corresponding action or response is triggered. If none of the expected values match the user's input, it's categorized as an **unidentified utterance**.
### Fallback
Fallback nodes can be linked directly to the voice input node. To specify the action in case of encountered issues or call failures, connect the **Fallback for failure** point to the subsequent node. To proceed with the next action if the user hasn't responded to the input, connect the **Failure for no response** point to the next node.
----
## Unidentified input storage
When the validation fails, the utterance is saved in the default table along with the following data:
* SID
* Phone Number
* Drop Step [same as the voice input node name]
* Utterance
* Recording URL
* Chat URL
* Language
* Translated Message
* Date & Time (of the call initiation)
* Issue `[UIU / Intent Missing - {{Intent name}}]`
---
## Call disconnection and call recording
Managing calls effectively is crucial to ensure seamless customer experience. The Yellow.ai platform offers several advanced call management options that enable you to configure your voice agent as per your specific requirements.
This article provides an overview of the additional call management options available on the Yellow.ai platform like **call disconnection** and **call recording** and how to configure them.
These are [node level options](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes#32-configure-node-for-a-voice-bot), you can find them by clicking the tools icon and selective voice options.
## 1. Configure your flow to disconnect a call
Enabling the call disconnect option will atutomatically disconnect the voice call when the respective node is reached in the flow.
**Use-cases:**
- Call disconnect can be used to **end a use case**.
- When the **agent is unable to understand the user's response** due to noise or any other reason, you can add a [condition node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/logic-nodes) to identify the user's intent and disconnect the call.
- When the user's input is not relavant despite repeated attempts, you can set maxium number of retries on the voice input node and disconnect once the limit is reached.
On the node (question, text, voice input, etc.) that you want to disconnect the call, configure the following:
1. Click the **Tools** icon > **Voice**.
2. Enable **Disconnect call**.
3. Click **Save**.
4. When this node is reached, the configured **bot says** message will be played, and the call gets disconnected. Example: *Thanks for the details*.
------
## 2. Manage call recording through agent flows
By default, the **end-to-end call is always recorded**, but you can change this behavior (**pause, stop, resume**) based on specific cases.
The Yellow.ai platform provides an additional option to manage call recording effectively.
> This must be configured for each node individually based on your use-case.
**Use-cases:**
- If the user shares sensitive information like a PAN number, you can pause the recording to prevent such information from being recorded.
- If you need to comply with regulations that require you to avoid recording the support agent and user conversation, you can configure the platform to pause the recording during that part of the conversation.
On the node (question, text, voice input, etc.) that you want to **pause** recording, configure the following:
1. Click the **Tools** icon > **Voice**.
2. Under **Recording action** select **Pause**.
3. Click **Save**.
:::info
You can also select **Resume** and **Stop** for other nodes. Resume will resume the paused recording and Stop will stop the call recording altogether.
:::
---
## Key components of a voice agent
Voice agents use advanced technologies for seamless and interactive communication via voice channels. Understanding the key **components** is vital for designing and implementing an effective voice agent system. These components facilitate efficient user interaction and communication.
This article highlights the basics of voice agent components.
:::info
#### Recap of the voice agent workflow
To understand the components of a voice agent, you must have a basic understanding of the [voice agent architecture](https://docs.yellow.ai/docs/cookbooks/voice-as-channel/voicearchitecture#2-workflow-of-a-voice-bot).
1. **Customer** initiates a **call** to the voice agent and makes a service request.
2. The customer's **speech is converted into text**. This text is then sent to the **telephony** platform, which acts as the interface between the cloud and the customer.
3. The text representing the customer's **request is processed** by the backend logic, which can be implemented through flows or custom code on the **Yellow.ai Cloud platform**.
4. Once the cloud platform understands the user's request, it generates a **response in the form of text**, which is then sent back to the **telephony** platform.
5. The voice agent **converts the response text into speech** and delivers it to the **customer**, allowing them to hear the response in a natural voice.
:::
#### Key components of voice agent workflow
The voice agent architecture consists of three key components:
1. **Capture user input**: The agent records and captures the customer's input.
2. **Understand user input**: The agent processes and comprehends the customer's input to generate a response.
3. **Customize agent response**: The agent plays or communicates the response back to the customer.
----
## 1. Capturing user inputs
There are three methods to capture user input on the IVR channel that is summarized below.
1. **Capturing user speech**: Yellow.ai platform incorporates Speech-to-Text (STT) and Automatic Speech Recognition (ASR) technologies for accurate transcription and real-time recognition of user speech. Through partnerships with leading STT engines like Microsoft and Google, we ensure high-quality transcription. ASR leverages advanced machine learning algorithms to facilitate seamless and precise communication between users and voice agents, enabling natural and interactive interactions. You can configure parameters such as STT engine, mode, and silence parameters for optimal performance.
2. **Capturing keypad (DTMF) input**: Users can provide input through the keypad while on a call, typically used for numeric inputs. Two configurations are available:
- **DTMF Digit Length**: Captures fixed-length user input, like a mobile number.
- **DTMF Finish Character**: Used for variable-length inputs, such as an application ID. Users can press "*" or "#" to indicate the completion of input.
> If there is no activity for more than 10 seconds, voice agent considers it as the end of input.
3. **Capturing keypad and speech as input**: In certain cases, the voice agent can allow users to provide input by either typing on the keypad or speaking it out. The agent recognizes the first response, whether it's from keypad activity or speech, as the final input.
--------
## 2. Understanding & responding to user responses
Operations on yellow.ai cloud platform must be performed to understand the user input that is available in text format and analyze and provide output in text format. For example:
- Bot training by adding [intent](https://docs.yellow.ai/docs/platform_concepts/studio/train/intents) and [entities](https://docs.yellow.ai/docs/platform_concepts/studio/train/entities).
- Configuring output for failure or no-response messages.
- Configuring validations against the context (intents, entities, pre-trained entities, etc).
- Many more...
------
## 3. Customizing agent responses
To make the users hear the agent's responses during a call, the text generated by the agent must be converted into spoken words. This conversion is achieved using text-to-speech (TTS) technology in collaboration with leading TTS engines such as Microsoft, Google, and Amazon. These engines provide a range of capabilities to meet different business requirements, including the ability to create customized and lifelike speech.
There are three ways to convert agent-generated text into speech on the IVR channel:
1. **Using pre-built neural voice models**: TTS providers offer pre-built neural voice models that can be utilized for quick prototyping and building demo voice agents. Design module and Voice input node enable the conversion of text into speech, providing a basic understanding of how the agent's responses would sound.
2. **Applying customization with SSML**: For more advanced use cases where precise control over speech synthesis is needed, Speech Synthesis Markup Language (SSML) can be employed. SSML in design module and voice input node allows for fine-grained customization of speech, like adjustments to speech rate, pitch, style, pauses, etc. By incorporating SSML in the text, the resulting speech can be highly tailored and expressive.
3. **Playing pre-recorded messages**: In some scenarios, it may be necessary to play pre-recorded messages during a call. For example, when a custom proprietary sound or a welcome tone needs to be played. Pre-recorded messages, in .wav or .mp3 formats, can be integrated into the call flow to provide a specific audio experience.
### Additional response customization on yellow.ai
Yellow AI offers extensive features for customizing agent responses. They are:
1. **Adding variables for custom responses (Dynamic messages)**: Personalize interactions with the agent by incorporating variables. By storing and using variables in the design module or voice input node, you can dynamically include user-specific information in the agent's responses, creating a more tailored experience. For example, you can dynamically include the user's name or city in the responses.
| Conversation 1 | Conversation 2 |
| -------- | -------- |
| **User**: I live in **Bangalore**. **Bot**: **Bangalore** is a great place! May I know your account number? | **User**: My name is **Sam**. **Bot**: Welcome to our store, **Sam**. What would you like to try first? |
2. **Using the translations page for multilingual agents (Multi-lingual flows)**: For multilingual agents, the [translations](https://docs.yellow.ai/docs/platform_concepts/studio/build/localization) feature can be employed to customize speech in different languages. This means that you can build a single flow and use the translations feature on the platform to store configurations for each language. You can provide localized experiences to users in different languages without the need to duplicate or recreate entire flows. This streamlines the development process and ensures consistency across different language versions of the voice agent.
> The translation text should be in SSML format.
---
## Understand delays in a conversation
Delays are the time between the user response and the voice agent response.
For example, the user response is "is there any discount?", and the delay is the time that the voice agent takes to process a line and respond to it.
The objective of the Telephony and Yellow cloud platform is to reduce the conversational delay and make the conversation more human-like.
Before understanding and configuring the voice agent for the best user experience in terms of minimising the conversation delay and still not cutting off the user mid-sentence, let's try to understand the way normal dialogue works.
1. When the response is a **Yes/No** value: This is supposed to be an instantaneous response and probably not a very long statement.
2. When the response is an **address**: This consists of multiple pauses/gaps and a longer time to complete the whole response.
> Ex: Door #1 < pause > Sector-D1 < pause > Kanpur Road < pause > Lucknow
3. When the response is a **phone number**: This will be a patterned delay and there will be a few pauses but the whole response is not very long.
> Ex: 99-44-32-06-11 or +1-202-795-3213
-----
## 1. Types of delays
Once we have understood how normal dialogue dealy works, let's have a look at other kinds of delay that are introduced in the voice agent conversation. After having a clear idea about the functioning of delays, we can better optimize the conversation around the same.
Delay (or perceived delay to the user) is the amount of time it takes after the user completes the query/response and the agent voice out the next response.
1. **STT delay**: When the user has responded and the telephony platform has received the audio file. This delay is caused when the audio file is getting converted to the text file on the STT engine. This delay depends on the number of characters, simple name response will take lesser time to process than an address.
> Ex: Audio-to-text conversation of "My name is Jake, what is my bank balance?"
:::note
The yellow cloud platform would have defined a range of duration for which the telephony platform accepts the response. For example, if the user is responding with a phone number we can ask the voice agent to only record it for 1 minute by setting the **Recording max duration**.
:::
2. **Telephony to yellow cloud platform**: The converted audio to text response will get transported from the telephony platform.
3. **NLP engine response time within cloud platform**: The text received on the yellow cloud platform will be sent to the NLP engine. Internally there will run a logical function where the software understands the user text response, finds a solution to continue the flow and generate a voice agent response.
4. **Yellow to telephony cloud platform**: The text response generated by the NLU-yellow cloud platform will get transported to the telephony platform.
5. **TTS delay**: This delay occurs while the agent response text is getting converted to an audio format by the TTS engine so that it can be played as a response to the user.
:::info
**TTS delay optimisation using cache memory**
**Use case**: Assume you own an ominous that converses with 1000 users in a day and the conversation flow is mostly the same. Ex: First agent question will be "what is your name" and the next would be to inform the user - "we have introduced a 0% intro APR offer on both purchases and transfers".
These repetitive messages or the small audio files remain the same throughout all the calls, hence the TTS delay that occurs while the NLP text response is getting converted to speech is optimised using **cache**. This skips the TTS delay and fetches the agent response from the cache database (present in the telephony platform).
The audio files generated from the first few user conversations are stored in the database and reused for the other calls reducing the overall latency.
:::
---
## 2. Configure delays for different use cases
Finally, after understanding the art of human dialogue and the system of voice agent, let us drill down on designing and configuring the agent in much better way.
While understanding the system delays, there were 3 major parts to it:
1. **STT**
2. **Telephony-Cloud Communication**
3. **TTS**
:::note
**Telephony-Cloud** stacks are very tightly integrated with each other and with a very reliable and fast NLP engine the whole delay for this section is negligible.
**TTS delay** is already very well optimized by using the caching mechanism explained above.
:::
Clever configuration lies is on how we optimize the STT delay. Let's understand that process below:
**Understanding STT detection**
**Use-case**: The agent asks the user "Are you sure you want to place this order?" and the user responds with Yes/No.
1. **Initial delay**: This delay occurs when the user hears the agent's response and takes time to process it before replying.
2. **Information delay**: The time taken for the user to speak the complete response.
3. **Pauses**: Pauses taken in between each of the words are considered a delay. Pause for a Yes/No answer will be nill and there will be multiple pauses while recording an address.
4. **Final dealy**: After the user has spoken the response, the duration of time the agent waits to understand that the user response is received and it must be processed as a single audio file.
:::note
To design a good voice agent you must configure these parameters at the [node level](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes#32-configure-node-for-a-voice-bot) based on the question being asked.
:::
### 2.1 Configure for Yes/ No response
> STT engine:: Microsoft and STT mode:: Streaming
| Parameters | Description | Min Value | Max Value |
|-------------------------|-----------------------------------------------------------------------------------------------|-----------|-------------|
| **Recording max duration** | Maximum duration after which the recording stops - the user response won't be accepted beyond this time. | 5 seconds | 60 seconds |
| **Initial silence duration**| Acceptable silence duration before a agent user starts speaking. | 5 seconds | 10 seconds |
| **Final silence duration** | Acceptable silence duration after a agent user starts speaking and the agent will have to process the response (Final delay must be greater than expected pauses). | 0.1 seconds | 5 seconds |
---
## Voice agent data handling
Coming soon!
---
## Call Details Report (CDR) of your voice agent on Insights module
:::note
In Data Explorer, CDR is available only for voice agents. The data will be updated after the call is completed.
:::
This article focuses on **Call details report** (CDR) for voice agents, a database table maintained by yellow.ai platform which records more than 15+ important metrics (like start time, duration, recording url etc) for each call.
## 1. Call details report overview
CDR is a report of telephony data obtained from each call (voice agent conversation with customer) for reporting and analytics purposes. Parameters of every call made through the **yellow telephony system** is recorded in the CDR, making it a reliable source of truth for call-related information.
- CDR fields help businesses gain valuable insights into their call center operations and customer interactions.
- The CDR table contains several fields that record various details about the call, such as **call duration, caller ID, called number, call status, and call type**. CDR fields are explained in the [last section](#4-cdr-fields-and-their-definitions) of this article.
- By analyzing CDR data, businesses can **identify trends and patterns** in their call center operations, **improve call quality**, and **enhance customer experience**, make **data-driven decisions** and **optimize** the voice agent operations for maximum efficiency and effectiveness.
Examples of insights you can derive from the auto generated call details report:
- Retrieve a list of users who disconnected calls during the last 7 days.
- Retrieve the answering rate for a specific campaign (identified by its ID) that was launched last Sunday.
- Retrieve daily total calls handled by the voice agent.
-------
## 2. Access call details(CDR) on Data Explorer
To access the CDR for voice agent:
1. Navigate to **Insights** > **Data Explorer**.
2. Open **Call details report**. You can see the report for the last 31 days.
3. You can **download** this report as CSV by clicking the **Actions** button.
--------
## 3. Visualize call detail report
On the data explorer, you have the option to filter or summarize the CDR data according to your specific needs. You can then visualize this data on a dashboard and download reports that only include the filtered data.
> Details on how to perform tasks such as summarization, visualization, and query creation are provided in this [guide](https://docs.yellow.ai/docs/platform_concepts/growth/dataexplorer/intro).
----
### Use case 1: Create custom dasboards
Suppose you're a ticket booking center using the yellow.ai voice agent, and you want to track the number of daily calls due to the different offers you provide. Here are the steps you can follow:
1. Open **Call details report** and click on the **Summarize** button.
2. Click on **Add metrics** and select **Number of distinct values of**.
3. Choose **Call ID** to track calls from different IDs, and then click **Save**.
4. To filter the data further to obtain daily stats, select **Timestamp** under **Group by** and choose **Day**. Click **Apply**.
5. You will now see a table with the required data. To visualize this data, click on the **Visualization** button.
6. Choose the type of visualization you want (e.g. bar graph), and click **Done**.
7. Click **Save query**, name your query, and then click **Save**. You can access this visualization as a **saved report** in the Data Explorer.
8. Whenever you want to view the number of users per day, you can directly open the saved report from the **Saved reports** section in the Data Explorer.
> You can also use this data to create your own custom dashboard. For instructions on how to do this, click [here](https://docs.yellow.ai/docs/platform_concepts/growth/Dashboards/dashboardintro).
-----
### Use case 2: Schedule reports to be sent to your email
Suppose you are a new support center on the yellow.ai voice agent, and you need to send a weekly report of the voice agent's billing duration to the accounts department. Here are the steps you can follow:
1. Open the **Call Details Report** and click the **Summarize** button.
2. Click **Add metrics** and select **Number of distinct values of**, then choose **Call ID** to fetch the unique calls attended by the voice agent.
3. Click **Add metrics** and select **Sum of** and **voice agent billing duration** to calculate the total billing duration for the selected timestamp.
4. To filter the data further and get weekly stats, choose **Timestamp** under **Group by** and select **Week**. Click **Apply**.
5. You will now see a table with the required data. Click **Save query**, name your query, and click **Save**.
6. (Optional) To visualize this data, click the Visualization button.
7. Go to **Data Explorer** > **Saved Reports** and open your custom report.
8. **Schedule** a weekly report by adding your email ID and the account team's email ID in the recipients field. Click [here](https://docs.yellow.ai/docs/platform_concepts/growth/dataexplorer/savedreportsactions#1-schedule-a-report) for the steps to **schedule report**.
> Understand other operations on [Insights modules](https://docs.yellow.ai/docs/platform_concepts/growth/introductiontoinsights).
----
### Use case 3: voice agent billing analysis
VoIP/IVR providers aim to bill companies accurately for channel usage. Analyzing call durations is pivotal. Quick disconnects within 5 seconds may not yield valuable insights and can be excluded from billing. For durations between 15 to 30 seconds, one billing rate applies, while calls exceeding 30 seconds fall into a different billing band. The Call Details report provides actionable insights for such billing scenarios. Follow these steps:
1. Navigate to **Insights > Data Explorer > Call Details report**.
2. Click on **Filters** and select **Callduration**.
3. Click **+Add buckets > Varied** and create billing buckets by adding Values like `<=5s`, `15-30s`, and `>=30s`.
4. Apply these buckets to categorize call durations, enabling a clear view for billing decisions.
----
## 4. CDR fields and their definitions
The CDR report provides the following information:
### Call ID
Call ID, or Call Identifier, is a system-generated unique identifier that is used to track and identify a specific phone call. It is used to keep track of various aspects of the call, such as its duration, call status, and other relevant information. Each call on the Yellow platform is assigned a unique Call ID, which can be used to look up details about the call in the platform's logs or reporting tools.
### Call start time
Call start time refers to the timestamp, at which the call was initiated by the caller. This timestamp marks the beginning of the call and is used to track when the call was started.
### Call end time
Call End Time refers to the time when a phone call or a communication session is terminated or disconnected.
### Ring Duration
Ring duration refers to the length of time that a phone rings before the call is either answered or goes to voicemail. It is the time between when an incoming call is received and when it stops ringing. Ring duration is typically measured in seconds.
### Call Duration
Call duration refers to the length of time that a phone call. It is the amount of time that starts from when the call is ringing, connected or answered and ends when the call is disconnected or ended. The call duration is important to measure for various reasons, such as billing purposes, quality assurance, and analysis of call traffic patterns.
### Voice Bot Duration
Voice agent duration, in seconds refers to the length of time that a voice agent or automated voice response system interacts with a caller during a phone call. This duration starts when the caller is first connected to the voice agent and ends when the call is transferred to a live agent or when the call is disconnected. The voice agent duration can vary depending on the complexity of the voice agent's responses and the options provided to the caller.
### Voice Bot Bill Duration
The duration, in seconds, of the conversation between the user and the voice agent, rounded up to the nearest Voice Billing Pulse interval for billing purposes.
### Campaign ID
A Campaign ID is a system-generated unique identifier assigned to a marketing campaign to track its performance and measure the effectiveness of marketing efforts. This field is empty for inbound calls by default.
### Hangup Reason
Hangup Reason refers to the reason why a call or communication session was terminated, ended, or disconnected. The possible values are **TTS failure, STT failure or Network faliure** (you may also find similar values with these descriptions: Normal Hangup, Bot failure, Bot response invalid, Bot response failure, DTMF over parent call, Message loop detected, Missed Consecutive DynamicNode Packets, Media download failure, STT resource not available, TTS resource not available, Network error, Invalid Destination, Phone Unreachable/Switch Off, Ring timeout, User Busy, Inbound Blocked)
Hangup Reason is a valuable metric for analyzing call center performance and identifying areas for improvement. By tracking and analyzing the reasons for call terminations, call centers can identify common issues, patterns, and trends, and take steps to address them to improve customer satisfaction and retention.
### Hangup Source/ Disconnected by
Hangup source/Disconnected by specifies the party that disconnected the calls. The possible values for this column are **User/Bot/System**.
- USER: When the customer itself disconnects the call.
- BOT: When the voice agent disconnects the call after providing the necessary information.
- SYSTEM: When neither voice agent nor the user disconnects the call and the call is disconnected due to any of the system issues.
Hangup Source can provide useful information for analyzing call quality, identifying problems with the network or equipment, and understanding the reasons for call failures.
### Source Number
Source number refers to the phone number or caller ID of the party that initiated the call. It is the number from which the call originated. In other words, it is the phone number of the person or device that made the call.
### Destination Number
The destination number refers to the phone number that received the call or message. It is the phone number dialed by the caller or the recipient of an inbound call.
### Call Status
The call status field refers to the final status of a call when it ended or was terminated. This field indicates whether the call was successful or not and can provide more details about the reason for call termination. Some common call status codes are **Answered, Not Answered, Failed, or Not Valid**.
### Direction
Specifies the direction of the call, either Inbound or Outbound. It could be **inbound**, meaning the call was received from an external source, or **outbound**, meaning the call was initiated by the user from the system.
### Recording URL
An URL to the end-to-end call recording of the call, which is usually recorded by default. Users have the option to pause recording during certain sections of the call or stop recording altogether as part of the voice agent logic.
The recording URL can be used to retrieve and listen to the recording of the call.
### SIP Code
For each call, an error code (SIP code) is generated to understand the hang up reason.
---
## Create flows to combine call and conversational details for analysis
This document outlines the application of **conversational details report** and **call detail report** parameters for customer tracking purposes.
Along with standard fields present in [CDR](https://docs.yellow.ai/docs/cookbooks/voice-as-channel/reporting/cdr) and [conversational details report](https://docs.yellow.ai/docs/cookbooks/voice-as-channel/reporting/convdata), voice agent developers can define fields based on their business logic requirements.
Examples of insights you can derive from the call and conversational details reports:
- Retrieve average call duration for callers from Gujarat state by combining **duration** fields from CDR table and **state** name from conversational details report table.
- Retrieve the success rate for answered calls with Hindi language selection by combining **call status** field from CDR table and selected **language** from conversational details report table.
------------
**Use-case:**
To analyze both call details and conversational details for certain use cases, you can create a flow that integrates data from both sources. By doing so, you can gain insights by analyzing the combined data.
For example, if you are developing a voice agent for medical counseling aimed at different age groups, it may be necessary to track the age of customers, the nature of their queries, and the length of their calls, in accordance with company guidelines. You could record the customer's age and query as custom fields, while the call duration can be automatically tracked by CDR. By combining both sources of data, you could create a dashboard that is tailored to this use case.
To accomplish use cases that involve using both conversational data and CDR data, three steps need to be followed:
1. Set up a flow that can **collect and store** custom details from the conversation.
2. **Create a callbackStatus** event that can retrieve CDR data once the call has ended.
3. **Merge** the CDR data and custom fields into a table for analysis.
-----
## Step 1. Call data collection and storage using variables
To store the age and query type along with the rest of the flow, follow these steps:
1. Create a flow on Automation using prompts to store conversational data in variables.
2. Create a table with required columns to store variable data.
3. Use database nodes to send variable data to a table.
> [Refer this](https://docs.yellow.ai/docs/cookbooks/voice-as-channel/reporting/convdata#1-create-a-flow-to-collect-and-store-custom-details-from-calls) for elaboration on these 3 steps.
------
## Step 2. Create a callbackStatus event
To streamline call management, create a custom event named `callbackStatus`. You can follow the steps provided [here](https://docs.yellow.ai/docs/platform_concepts/studio/events/event-hub#-8-custom-events) to create a custom event. Once you've created the event, verify that its status is set to **Active**.
#### Functionality of callbackStatus custom event
The `callbackStatus` object is a container that holds important CDR data and is dispatched to the platform immediately after a call is disconnected. In addition to this, an event is also dispatched to the platform as soon as the call is disconnected, which can be utilized by bot developers to receive the 'callbackStatus' JSON object.
------
## Step 3. Merge CDR and conversation data post-call disconnection
1. Create a new flow from scratch by following the steps provided [here](https://docs.yellow.ai/docs/platform_concepts/studio/build/Flows/journeys#2-create-a-flow).
2. On the start node, add an [event trigger](https://docs.yellow.ai/docs/platform_concepts/studio/build/Flows/configureflow#trigger-flow-using-event) by selecting **Event** as the trigger and `callbackStatus` as the value. This will ensure that the flow executes when the call has ended as per the backend logic.
3. Create new [variables](https://docs.yellow.ai/docs/platform_concepts/studio/build/bot-variables#-3-create-a-variable) to retrieve CDR-related entries. For example, to retrieve **Call duration**, create a variable *Duration* and add value as `{{variables.EVENT_DATA.duration}}`. [Click here](https://docs.yellow.ai/docs/cookbooks/voice-as-channel/reporting/variables#variables-available-for-disconnected-calls) for detailed explaination.
4. Add a [database](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/database-node) node to combine CDR and conversational detail fields [into one table](https://docs.yellow.ai/docs/cookbooks/voice-as-channel/reporting/convdata#step-1-create-a-flow-to-store-data-in-variables).
- Add type as **Update**. Select the same table name.
- Filter for **SID**.
- Add CDR fields/variables.
------
## Step 4. Download or visualize call details for better insights
You can find all the information related to your use case, including data from both CDR and conversational detail fields, on the table.
1. To download this data, navigate to **Automation** > **Database**, and click on **Table actions**. From there, you can easily download the data.
2. You can also view this data on **Insights** > **Data explorer**, where it can be summarized, visualized, and even added as a custom dashboard for easy access to analytics.
---------
**Understand other operations on insights**
- Check out the available actions for custom tables by visiting [this page](https://docs.yellow.ai/docs/platform_concepts/growth/dataexplorer/customtables).
- To visualize the data collected from calls, follow the steps outlined in [this guide](https://docs.yellow.ai/docs/cookbooks/voice-as-channel/reporting/cdr).
- Understand other operations on [Insights modules](https://docs.yellow.ai/docs/platform_concepts/growth/introductiontoinsights).
---
## Extract user responses from conversations and create custom reports
In this document, we will cover a use case where custom fields are used to track customer details obtained from the conversation.
**Conversational details that can be tracked during the call**
Voice agent developers have the ability to define custom fields based on their business logic requirements, in addition to standard fields. This allows them to derive additional insights from their data. A few examples of custom details are additional phone numbers, ages, names, etc.
Examples of insights you can derive from the conversational details report:
- Retrieve the percentage of callers who are selecting the Hindi language option.
- For an e-commerce chat agent, retrieve the percentage split between inquiries related to order status and those related to registering a complaint.
-----
## 1. Create a flow to collect and store custom details from calls
**Use-case to understand how to create reports with conversational details data**
If you are developing a voice agent for educational counseling for students across various age groups, it may be required as per company guidelines to keep track of the customer/student's age and the type of query asked. This information can be recorded as custom fields, allowing you to gain insights into the types of queries being asked by different age groups.
### Step 1. Create a flow to store data in variables
To store the age and query type along with the rest of the flow, follow these steps:
1. Go to **Automation** and create a flow that supports your use case.
2. In the node that collects age and query type, select **Store response in** a variable.
--------
### Step 2: Create a table to store variable data
To store data collected from flows, you need to create a table (this is a prerequisite to step#3). Follow these steps:
1. Go to **Automation** > **Database**.
2. Create a **table**. Add field names and mark them as **Searchable**.
3. The database will store all the details obtained from the calls.
> [Learn more](https://docs.yellow.ai/docs/platform_concepts/studio/database#-1-create-table) about creating a table in Automation.
------
### Step 3: Use DB node to send variable data to a table
To store all the collected details in a table, add **database** nodes to the flow(step#1) after collecting each variable, using the following steps:
1. Add a **database** node at the beginning of the call to send the system-generated unique identifier (**SID**) value to the table.
* Select the type as **Insert** and add the table name.
* Under records, add the field as **SID** (column name) and the value as **mp_sid** (the custom variable name you have created for the SID).
:::info
SID is a voice data variable which is available immediately after the call is initiated and can be used as a filter for subsequent database nodes.
> [Learn more](https://docs.yellow.ai/docs/cookbooks/voice-as-channel/reporting/variables) about voice data variables.
:::
2. Add **database** nodes after storing responses in a variable.
* Select the type as **Update** and add the table name.
* Add a **filter** `Where SID = mp_sid` to ensure that the data is added only if the SID is the same.
* Add variables, for example, after collecting the Age, add the Age value to the table.
To ensure that you have the customer details even if the customer disconnects in the middle, add a database node after every prompt node to send the collected data to the table. This data can then be used to reach out to the customer or as a survey.
> [Learn more](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/database-node) about the DB node.
-----------------
## 2. Download or visualize conversational details for better insights
1. To download this data, navigate to **Automation** > **Database**, and click on **Table actions**. From there, you can easily download the data.
2. You can also view this data on the **Data explorer**, where it can be summarized, visualized, and even added as a custom dashboard for easy access to analytics.
---------
**Understand other operations on insights**
- Check out the available actions for custom tables by visiting [this page](https://docs.yellow.ai/docs/platform_concepts/growth/dataexplorer/customtables).
- To visualize the data collected from calls, follow the steps outlined in [this guide](https://docs.yellow.ai/docs/cookbooks/voice-as-channel/reporting/cdr).
- Understand other operations on [Insights modules](https://docs.yellow.ai/docs/platform_concepts/growth/introductiontoinsights).
---
## Voice agent overview (voice dashboard)
:::note
The voice agent overview on Insights will only be available for voice agents.
:::
The voice agent overview dashboard is built on top of the CDR data and tracks valuable metrics in a more visual and intuitive manner for effective reporting.
The Voice Overview Dashboard includes the following key metrics:
1. User traffic metrics such as calls and duration
2. Analysis of call statuses
Examples of insights you can derive from the dashboard:
- Retrieve the total number of calls received in the past week.
- Retrieve the average duration of calls for the previous 30 days.
- Retrieve the answering rate for the outbound campaign during the last quarter.
**Voice dashboard on Insights**
To view the voice dashboard, navigate to **Insights** > **Voice dashboard**.
---
## Maximizing Business Outcomes with Voice Bot KPI Tracking
If you're using a voice agent, tracking your metrics is essential for achieving the desired results. Yellow's platform offers comprehensive tracking to give you complete insights into your voice agent's performance.
## 1. Voice reports available on Insights
You have two options to track your voice data:
1. **Basic Reporting**: The platform automatically tracks common points from the voice conversation and displays them on the [Voice Overview Dashboard](https://docs.yellow.ai/docs/cookbooks/voice-as-channel/reporting/dashboard) on Insights module. From the dashboard, you can:
- Retrieve the total number of calls received in the past week.
- Retrieve the average duration of calls for the previous 30 days.
- Retrieve the answering rate for the outbound campaign during the last quarter.
2. **Advanced Reporting**: You can track voice agent analytics on Insights based on your specific needs in the following ways:
1. [CDR reports](https://docs.yellow.ai/docs/cookbooks/voice-as-channel/reporting/cdr): View more than 15 voice call parameters on the **Call Details Report** (CDR) in the Data Explorer. From the CDR report, you can:
- Retrieve a list of users who disconnected calls during the last 7 days.
- Retrieve the answering rate for a specific campaign (identified by its ID) that was launched last Sunday.
2. [Conversational details reports](https://docs.yellow.ai/docs/cookbooks/voice-as-channel/reporting/convdata): **Design custom flows** to track the specific information you need from the customer, save it in a database, and visualize it. From the conversational details report, you can:
- Retrieve the percentage of callers who are selecting the Hindi language option.
- For an e-commerce chat agent, retrieve the percentage split between inquiries related to order status and those related to registering a complaint.
3. [CDR X Conversational details report](https://docs.yellow.ai/docs/cookbooks/voice-as-channel/reporting/conv_cdr): Use **complex queries** to combine **Call Details Report** (CDR) and **conversational data** and create custom reports. From this report, you can:
- Retrieve the average handling time for calls in the Hindi language.
- Compare the average handling times of calls for use case A versus use case B in the voice agent.
Further articles provide detailed explanations of these use cases.
-----
## 2. Usage of voice agent reports
Below are some instances that can be obtained from the voice agent reports:
| Use-cases | Insights |
| -------- | -------- |
| **Customer service management** | Custom fields can be used to track customer details and gather insights into the types of queries being asked. For example, a customer service agent for a telecommunications company could use custom fields to track the types of service issues being reported by customers in different regions, allowing the company to identify patterns and address recurring problems.|
| **Sales and marketing** |Custom fields can be used to track customer preferences and interests, allowing sales and marketing teams to tailor their messaging and offers. For example, an e-commerce company could use custom fields to track the types of products customers are interested in and target them with personalized promotions |
| **Education and training** | Custom fields can be used to track student progress and gather insights into areas where additional support may be needed. For example, an educational counseling agent could use custom fields to track the types of questions being asked by students in different age groups, allowing counselors to identify areas where additional resources may be needed.|
| **Healthcare** | Custom fields can be used to track patient information and gather insights into health trends. For example, a healthcare agent could use custom fields to track patient symptoms and conditions, allowing healthcare providers to identify patterns and provide more effective treatment.|
| **Financial services** | Custom fields can be used to track customer financial information and gather insights into spending habits. For example, a banking agent could use custom fields to track customer spending by category, allowing the bank to identify areas where customers may benefit from additional financial products or services.|
| **Travel and hospitality** | Custom fields can be used to track customer preferences and gather insights into travel trends. For example, a travel booking agent could use custom fields to track the types of destinations and travel experiences customers are interested in, allowing travel companies to tailor their offerings to meet customer needs. |
| **Identifying customer trends** | CDR reports can provide insights into customer behavior, including the types of calls received, the most common reasons for calling, and the most frequent customer complaints. This information can be used to improve customer experience and drive business growth. For example, a marketing team may use CDR reports to identify common customer pain points and develop targeted campaigns to address them. |
|**Evaluating call quality**|CDR reports can provide insights into the quality of calls, including call duration, call wait time, and call drop rate. A business may use this data to identify trends and areas for improvement. For example, a call center may use CDR reports to identify common issues that cause calls to be dropped and take steps to address them.|
|**Analyzing call volume**| CDR reports can help businesses track call volume, including the number of calls received, missed, answered, and abandoned. For example, a customer service team may use CDR reports to analyze their call volume and determine the busiest times of day.|
|**Call Duration Analysis** | Businesses can use CDR reports to analyze the average call duration. This can help identify if customers are spending too much time on call or answering multiple questions posed by that voice agent without completly understanding the intent. |
|**Measuring chat agent performance** | With CDR reports, businesses can track how well their chat agent is performing. They can see metrics such as the response time, resolution rate, and error rate, which can help them identify areas for improvement and optimize their chat agent for better customer service.|
|**Assessing chat agent ROI** | By tracking the number of conversations and the time spent on each conversation, businesses can calculate the ROI of their chat agent investment. They can also track how many leads or sales were generated as a result of chat agent conversations.|
|**Monitoring compliance** | Businesses in regulated industries, such as finance or healthcare, can use CDR reports to monitor compliance with industry regulations. They can track the conversations and ensure that their chat agent is providing accurate and compliant information to customers.|
---
## Access voice variables within a flow in Automation
## 1. Types of voice variables
**Voice agent variables** are similar to regular [variables](https://docs.yellow.ai/docs/platform_concepts/studio/build/bot-variables), with the only difference being the way they are acquired. There are two types of voice variables that can be utilized in the process of building a flow in studio:
1. **Bot variables**: These variables are automatically available to the agent at the beginning of the voice call.
2. **CDR variables**: These variables are obtained once the call is terminated and are the [CDR values](https://docs.yellow.ai/docs/cookbooks/voice-as-channel/reporting/cdr) that are created for reporting purposes.
-----
## 2. Access voice variable values
To work with [conversational details reports](https://docs.yellow.ai/docs/cookbooks/voice-as-channel/reporting/convdata) or [call and conversational details reports](https://docs.yellow.ai/docs/cookbooks/voice-as-channel/reporting/conv_cdr), you may require access to voice variables (default and CDR). To push the necessary values into the database node and tables, you must create variables. Follow the steps below:
1. Open the variables tab and add a variable by selecting *Global variable*.
2. Add a custom variable **name** and select the variable **data type** (usually a string). Add the **value** (you can only use the variables given in the section below) and click **Add**.
> To learn more about variables, visit [this](https://docs.yellow.ai/docs/platform_concepts/studio/build/bot-variables) page.
----
### Variables related for ongoing calls
Once the call is initiated, these voice agent variables (global variables) are accessible throughout the flows in the voice agent. To retrieve these variables, use the following format:
| Format | Datatype| Description|
| -------- | -------- | -------- |
|`{{{data.call_sid}}}` | String | A unique identifier assigned to each voice call |
| `{{{data.recording_url}}}` | String | The downloadable URL of the ongoing call |
| `{{{data.from}}}` |String| The phone number the call was made from|
| `{{{data.to}}}` | String| The phone number the voice agent called |
| `{{{data.direction}}}` |String | Inbound or outbound call|
| `{{{data.detected_language}}}` | String | The language of the conversation that was identified (only present when auto-detect option is enabled)|
----
### Variables related for disconnected calls
Additional details are only obtained after the [callback event](https://docs.yellow.ai/docs/cookbooks/voice-as-channel/reporting/conv_cdr#step-2-create-a-callbackstatus-event) is triggered, which can be retrieved by creating a new flow that executes after the call ends. To retrieve these details, use the following format:
| Format | Datatype| Description|
| -------- | -------- | -------- |
|`{{variables.EVENT_DATA.duration}}` |String| The total duration of the call, including ring time, agent transfer, etc.|
| `{{variables.EVENT_DATA.voice_bot_duration}}`| String| The duration for which the voice agent was speaking|
| `{{variables.EVENT_DATA.voice_bot_bill_duration}}` |String| The duration considered for billing purposes|
| `{{variables.EVENT_DATA.disconnected_by}}`|String| The entity responsible for disconnecting the call (either Bot or User)|
| `{{variables.EVENT_DATA.status}}` | String| The call status (answered, not answered, or failed) |
---
## Streamline customer support by connecting voice agent to live agent
Businesses can set up customer support process to transfer a customer's interaction from yellow.ai's voice agent to a human agent. This can typically by used when the voice agent cannot resolve the customer's issue, or when the customer requests to speak to a human.
In this article, you will learn how to configure your voice agent to transfer the voice call to a support agent.
## 1. Overview of call transfer to an agent
On the Yellow platform, to transfer a user's call to a human agent, the platform makes a call to the agent, who subsequently answers the call.
The platform then connects the end user's call to the agent, allowing the user to speak directly with the human agent.
#### Scenarios for voice agent transfer to an agent
There are various situations in which transferring a call to a human agent becomes necessary. The Yellow.ai platform offers a dedicated flow that can be configured for seamless call transfers. Here are two common scenarios:
1. **Fallback limit reached**: This flow is utilized when the voice agent repeatedly fails to comprehend the user's query or when the user's query goes beyond the scope of the agent's predefined intents.
2. **User intent for human agent**: This flow is activated when the user explicitly expresses the need to speak with a human agent, as indicated by an identified intent in their response.
----------
## 2. Set up call transfer to an agent
Follow the steps below to create a workflow to transfer a voice call to an agent:
### Step 1: Set up live agents
To configure live agents for your voice agent on Yellow.ai, you need to establish a connection between Yellow.ai and a third-party live agent support platform such as Genesys PureCloud Live Agent or Freshchat. Follow the steps below:
1. Sign up with the [third-party live chat platform](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/overview#6-live-chat ) and set up your live agent team, who will be available to receive calls.
2. Obtain the necessary credentials from the third-party platform. These credentials will be used to connect Yellow.ai to the live agent integration.
3. Refer to the [integration articles](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/overview#6-live-chat) for the specific instructions on how to connect the chosen live chat support application with Yellow.ai.
4. Once the configuration and connection to the third-party tool are completed, during an ongoing voice agent call when agent transfer is required, Yellow.ai will send a request to the third-party tool to establish a connection between the voice agent customer and the live agents.
----
### Step 2: Design flows to transfer calls
To streamline customer support for your voice agents, you can incorporate flows from the above mentioned [scenarios](#scenarios-for-voice-agent-transfer-to-an-agent).
#### 1. Flow to transfer a call to an agent when the fallback limit exceeds
When the voice agent repeatedly fails to understand the user's input or when the conversation goes beyond the agent's capabilities, it's considered a fallback scenario. To handle this, you can set the fallback flow to execute the **transfer to agent** flow or set up a **node** to forward the call to an agent.
1. Identify the voice input node where the agent transfer should occur. For example, if the voice input node (e.g., phone number) repeatedly triggers fallback scenarios, the agent can automatically transfer the call to a live agent.
2. Connect the node's **fallback for failure** and **fallback for no response** to the agent transfer.
3. Establish connection through another voice input or prompt node: If you choose the voice input node, you can simply enter a message in the **Bot asks** field, which will be played before the call transfer. Use the **make prompts smarter** icon to configure the [forwarding details](#step-3-add-call-forwarding-details).
(or)
3. Use an execute flow node to connect to an agent: This can be combined with the second scenario where an intent triggers the *Chat with agent flow. In this case, create a new flow called *Chat with agent* and add a prompt node. Enter a message in the **Bot asks** field to be played before the call transfer. Use the **make prompts smarter** icon to configure the [forwarding details](#step-3-add-call-forwarding-details).
**Main flow**:
**Chat with agent flow**:
4. When a fallback is encountered, the call will automatically be transferred to a live agent.
---
#### 2. Flow to transfer a call to an agent when the user requests for it
This flow is activated when the user explicitly expresses the need to speak with a human agent. You can set specific intents or keywords that indicate the customer's desire to speak with a human agent.
1. Create an [intent](https://docs.yellow.ai/docs/platform_concepts/studio/train/intents) called `chat with agent` with relevant utterances indicating the customer's desire to speak with a human agent.
> The utterances can include phrases such as "you are not able to understand me, I need someone else," "I want to talk to the manager," "connect me to someone," or "I can't understand, I want to talk to your executive."
2. Set up a [new flow](https://docs.yellow.ai/docs/platform_concepts/studio/build/Flows/configureflow#configure-start-trigger) with the start trigger configured as the intent `chat with agent`.
3. In the flow design, add nodes as needed and end the flow with a prompt node. Enter a message in the **Bot asks** field, which will be played before the call transfer. Click **make prompts smarter** icon and configure the [forwarding details](#step-3-add-call-forwarding-details).
----
### Step 3: Add call forwarding details
To configure call forwarding options at the [node level](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes#32-configure-node-for-a-voice-bot) for each node, follow the steps below:
> **Prerequisite**: Inside the dedicated `Chat with agent` flow, add a question/voice input/speak node to trigger the call transfer to an agent. Configure the message that the agent will play before transferring the call.
1. Click on the **make prompts smarter** icon, select **Voice**.
2. Enable **Forward call**.
3. Enter the forwarding details:
|Field Name| Description |
| -------- | -------- |
|Forward call| Enable this to forward the call at the specific node.|
|Number to forward or SIP extension| Either define the **number to forward** or **SIP extension** of the contact center or live agent.|
|Caller ID number for Agent screen(Caller line identity) | You can define the caller ID to be shown on the agent screen. If left empty, the voice agent number will be displayed on the agent screen as it is making the call to the agent. If supported, the end-user number can also be shown on the agent screen.|
|Sending Contextual Meta Data to Agent (Custom SIP headers) | Transfer contextual information such as the user's name, age, and query to the agent so that they are aware of these details before the call is connected.|
**Sample agent screens with the forwarding details**:
> You can configure recording options after the call transfer on the [tools section](https://docs.yellow.ai/docs/platform_concepts/studio/tools#recording-related-voice-settings).
---
## Call recording
Depending on the different use-cases and different kind of compliances that comes along with the industry regulations, we have designed a recording management feature that allows user to pause, resume or stop call recording during the conversation.
:::note
By default, the call recording feature is enabled to record the conversation.
:::
## 1. Configure call recording
By default, call recording is turned on by default for all the voice agents. In case, you want to pause it for some recording sensitive conversation like OTP or ID number, you will have to configure the recording action on the [node level options](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes#32-configure-node-for-a-voice-bot).
**To pause recording**
1. Set the recording action to *pause* on that specific step.
2. Set the recording action back to *resume* on the very next step following the sensitive step/s.
:::info
1. Once you stop the recording for a call at any step, it can’t be resumed again.
2. You can also configure the recording behaviour in case the conversation is transferred to an Agent. Set the required recording action on the [global options](https://docs.yellow.ai/docs/platform_concepts/studio/tools#25-voice). Setting it to True will record the conversation with the agent and vice-versa.
3. Recording action can only be set for the specific turn. If you set it to pause, all three, options below are not captured for the turn:
- Question asked by agent.
- Response from the user.
- The processing duration.
:::
## 2. Implement call recording
**Use case**
- Pausing the recording while the user provides the Aadhar number to the agent.
- On the question node where the agent asks the user to provide the Aadhar details, the agent developer can set the recording action to *pause*.
- On the next node, where the agent follows up with another question (non-recording sensitive), *resume* the recording action.
---
## DTMF
Dual-tone multi-frequency (DTMF) is used for touch tones, it is the sound made when pressing a number key. For cases, where we expect background noise and difficulty in correctly identifying the user utterance for numeric inputs, we can use this feature to record user responses.
## 1. Configure DTMF for agents
To configure DTMF, you can use the below-mentioned node level options:
1. Capture DTMF and Configure DTMF Digits Length.
(OR)
2. Configure DTMF Finish Character and Capture voice with DTMF input.
| Fields | Description |
| ----------------------------- | ----------- |
| **Capture DTMF** | Enable this option if the DTMF is to be collected on the specific node. |
| **Capture voice with DTMF input** | With this enabled, the agent will be able to capture both voice and DTMF for the same question. Example - What is your mobile number? Note - Bot will only capture the one which comes first from the user be it speech response or DTMF response. |
| **DTMF digital length** | Enter the length of characters to be captured. Ex: For an Indian phone number, it is 10. |
| **DTMF finish character** | Character which defines when the agent must stop capturing. Supported finish characters - "*" and "#" |
:::info
> Either DTMF digital length or DTMF finish character can be configured.
DTMF digit length, DTMF finish character and DTMF timeout are 3 ways in which the agent understands when to stop capturing:
1. Digit Length is useful when you are capturing fixed-length data. Ex: Phone number.
2. Finish character is useful when you don't know the length and that could vary depending upon different states/products. Ex: Model id, application number. A user can define either "*" or "#" to inform that all Digits are added.
3. DTMF timeout is a default inactivity timeout (not open for configuration) and it is set to 10 seconds by default (it overrides **digit length** and **finish character**). For example, if the length is 11 and the user has only entered 6 characters, and there are 10 seconds of inactivity, only those will be captured.
:::
## 2. Use-cases
DTMF can be used in following ways while building a voice agent:
1. Business requirements specifically know when and where to collect DTMF input as part of the conversation - via. number capture.
The components which can be used to build such a flow are Question/Text node and DTMF Node Level Options.
Example: Question/Text node + Call forward.
> If the agent wants to collect numeric input for a mobile number or application number. As a part of agent logic agent can also collect this information via DTMF (saying “Please input your 7-digit application number to proceed ahead.”) along with a voice response from the user.
2. As a fallback mechanism agent allow the user to enter numeric response using DTMF. Also, if the agent is not able to correctly understand due to background noise, the input can be DTMF oriented.
The components which can be used to build such a flow are [separate flows](https://docs.yellow.ai/docs/platform_concepts/studio/build/Flows/journeys) + DTMF Node Level Options.
> One more use case could be where the voice agent for some reason isn’t able to understand the user’s numeric response/query and hence we can have a dedicated flow as a fallback option where we let the user enter a numeric option using DTMF too.
---
## Understand Context-Aware Interruption Handling in voice bots
(Available in Private-Beta)
Voice is a full duplex channel, i.e. even when the agent is speaking something, if the user has some clarification or doubts, they expect the agent to listen and answer those queries first. From a user behavior perspective, this is equivalent to a customer interrupting a Human-agent while the agent is speaking something on a call.
Our new design approach for the feature is influenced by the way humans process interruptions over call. Likewise, humans are smarter to listen to interruptions, judging the validity of all the interruptions in parallel and only stopping when a valid (intended) interruption is observed. In case an invalid interruption is observed, the agent will automatically ignore that and be on track with the ongoing conversation. Detailed conversational flow is demonstrated below for both valid and invalid interruptions.
To ensure that only relevant inputs from the callers are respected as Interruptions, the Voice Bot can now be configured to define what constitutes a Valid interruption:
1. **Positive case**: With the new feature of interruption, the agent will only stop speaking (moving away from the current conversation) when it’s a valid interruption (that is acceptable in the context of the conversation).
****
2. **Negative case** : If there is a background conversation (unrelated to the current context of agent conversation) that gets picked up by the agent, it will be treated as an invalid interruption and the flow will not be broken (the interruption will be ignored).
****
**Voice Options (to be used)**:
1. Set the below options to interject
```
interject = true;
interject_early : true (optional)
```
2. Dynamically set the below option for a posted utterance to respond or ignore:
```interjection_response: "no_action"; (OR "take_action")```
:::note
1. This new feature is under private beta only and will only be enabled (on the agent) after evaluation of a valid use-case requirement.
2. Currently the platform doesn’t evaluate the validity of the interruption but instead needs to be handled via agent logic (ex - if entity = language then next node, else ignore)
3. Only 1 user interruption will be respected per node to start with under private beta.
:::
---
## Understand language detection in voice agents
You can now interact with the agent in multiple languages without the need to manually select the language each time you use it. The agent will automatically recognize the language you are speaking and respond accordingly.
The success of an automated Voice conversation depends heavily on the correct transcription of the caller’s speech inputs to text with the help of third-party speech-to-text services.
With Language detection, each step can now be configured with a set of languages (as opposed to a single language limitation in earlier implementation).
In addition to the ability to accept multiple languages, Language detection also detects the language being spoken on the call and sends this information back to the Bot for relevant actions (like changing the language of the conversation from English to Hindi). For Example:
* **Bot question**: “Welcome to Yellow Bank. How can I help you today”
* **User input configuration**: Expected Language = English, Hindi, Gujarati
* **User says**: “मेरे खाते का बैलेंस कितना है? (What is my Account Balance?)”
* **Bot question**: “क्या आप मुझे अपना 12 अंकों का अकाउंट नंबर बता सकते हैं” (Can you please share your 12 digit account number with me?)
**How to utilize this feature?**
This feature is part of the new voice 2.0 architecture. To utilize this, while passing the *STTlanguage parameter* (voice options), pass all the expected STT language codes comma separated. For example, if you are at a phone number node, pass the node level option of STT_language as “en-IN,hi-IN” to enable auto-capture in both English and Hindi for that specific node only.
> The switching of agent language needs to be part of agent logic. This is not a direct platform feature in v1.
**Usage recommendations**
Language detection is an additional processing overhead for the STT engine and hence should be used at selected steps. Using this across all the steps will probably result in higher conversational latency. From our internal testing, the additional latency is directly proportional to the number of languages added for detection.
---
## STT (Speech to Text)
Coming soon!
---
## Understand how a call gets transfered to customer support agents
Coming soon!
---
## TTS (Text to Speech)
Coming soon!
---
## Wait music for APIs
Without **Wait Music**, the silence on the call while executing APIs results in a sub-optimal conversational experience. To improve the conversation, wait music can be added in the API node settings.
When the wait music is configured for high latency API calls, it allows voice bot developers to play music on the call while waiting for the API response. After the API call is completed, the wait music is stopped and the further steps (nodes) are executed.
You can configure the wait music in the [API node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/api-node) where bot developers can upload a public URL or upload a music file.
> **Supported formats for wait music files**: .mp3 and .wav.
:::note
- Wait music option on API nodes work only for voice agents.
- This feature is an add-on hence nothing changes on the LIVE agents. Though, the team recommends implementing wait music if the latency of some APIs is high for a better user experience.
- Ensure that the **Wait Music Length** (duration) is greater than the timeout configured for the API for a better experience to avoid unseen race condition scenarios.
:::
---
## Voice AI agent
**Why use yellow.ai's cloud platform to build your first AI-voice agent?**
| What we provide? | What you can do? |
| -------- | -------- |
| **Harness advanced AI** | Leverage cutting-edge technologies like natural language processing and machine learning to provide intelligent and engaging customer experiences that set you apart. |
| **Automate human-like interactions** | Free up resources by automating repetitive tasks, such as FAQs and basic troubleshooting, allowing your team to focus on delivering exceptional service and driving growth.|
|**Scale efficiently** | Handle high volumes of customer inquiries without the need for additional agents, saving time and costs while maintaining efficient support operations.|
| **24/7 availability** | Be there for your customers anytime, anywhere with round-the-clock support, building loyalty and trust by providing instant assistance whenever it's needed. |
| **Personalize experiences** | Capture customer data and tailor interactions, offering targeted suggestions, promotions, and support that create personalized experiences and foster long-lasting relationships.|
| **Data-driven insights** | Gain valuable insights from customer interactions, uncover trends, and optimize processes to make informed decisions and enhance your customer service strategies.|
| **Easy integration** | Experience a seamless integration process with Yellow.ai's user-friendly platform, getting you up and running quickly with their intuitive agent development and deployment tools.|
:::info
:unlock: : **[Sign up today](https://cloud.yellow.ai/auth/login)** to integrate your business with Yellow.ai's voice agent and elevate your business to new heights.
:::
---
## Yellow's voice agent system architecture
In this article, we will focus on an **inbound voice call use case** to understand the workflow of a voice agent.
-------
## 1. Types of voice calls
There are two different types of calls that a voice agent can handle, **Inbound and Outbound**. Calls mainly classified based on how they are initiated and why they are initiated.
| Type | Initiation method | Purpose of the call |
| -------- | -------- | -------- |
| **Inbound** | Inbound voice calls are calls that are initiated by the voice agent user(caller/customer) and received by the voice agent. | Inbound voice calls to a voice agent are usually made by customers or users who need to interact with the voice agent to get information or perform an action. |
|**Outbound** |Outbound voice calls are initiate by the voice agent itself.| Outbound voice calls from a voice agent are usually made for specific reasons, such as sending notifications, reminders, or alerts to users.|
----------
## 2. Workflow of a voice agent
Yellow's voice agent system architecture comprises two primary components, which work together to enable the agent's smooth functioning.
1. **Telephony Platform**: This component handles voice processing related tasks such as initializing calls, call forwarding, and call waiting. It provides the necessary platform capabilities for the voice agent to function efficiently.
2. **Yellow Cloud Platform**: This component is responsible for the business logic, conversation flow, and natural language processing (NLP).
This section explains workflow of an **inbound** voice agent call. Follow the steps below:
### Step 1: Initialize a conversation
1. When a user initiates a call (by calling to the configured support number), the Telephony platform identifies an incoming call.
2. Telephony platform sends a request to Yellow platform to make a call with the user's phone number and the voice agent's phone number.
`Incoming request from: User number +9187386*****`
`Send request to: Company number +9178903****1`
3. The Yellow Cloud platform verifies the company number to identify the agent.
`Company number +9178903****1 belongs to XYZ company`
`Initialize XYZ agent`
4. The voice agent starts the home flow to initiate a conversation, which is the first flow executed when the agent begins a conversation.
`#WelcomeFlow: Hey! I am XYZ agent, what is your name?`
5. First node of the home flow will be processed on the Yellow platform and sent to the Telephony platform.
`Question node: "Hey! I am XYZ agent, what is your name?"`
6. The user hears the voice agent's request in form of speech.
`Voice response(TTS): "Hey! I am XYZ agent, what is your name?"`
### Step 2: Continue agent conversation
After the voice agent's home flow, the first node of the flow gets processed on the Yellow platform and sent to the Telephony platform in the form of speech.
1. The user hears the voice agent's request and replies to it.
`User response: "I am Jake, I want to know my bank balance."`
2. The Telephony platform sends the user's response to the Yellow Cloud platform, where the voice agent identifies the intent and generates an output.
`Intent: "Check bank balance."`
`Response agent logic: "Ask account number."`
3. Further logics are executed and output is sent to the user via the Telephony platform in the form of speech. This workflow continues until the conversation ends or the user disconnects the call.
---
## Voice FAQs
What are the languages supported for Voice Bot?
Language support depends on the STT/TTS engine selected. Languages supported in Microsoft engine.
Can yellow voice agents support DTMF inputs?
Yes, voice agents support both speech recognition and DTMF (keypad) inputs. Learn more here.
How will voice-agent work with third-party CRM?
It can integrate with any CRM for picking up information or posting back updates as long as we have APIs available to configure.
How can the voice agent transfer contextual information (like name, number, etc) collect from the end user to the contact center as well?
We can use SIP Header transfer or Tonetag transfer to pass extra information while doing the call transfer.
What are the STT engines provided for configuration?
Currently we have native integrations with Microsoft and Google for our STT services.
Can the agent be configured for regional languages?
Yes, a voice agent (same as a chat agent) can be configured for multiple languages.
How a voice agent can capture alphanumeric inputs accurately from user speech?
Accuracy depends on many factors like the complexity of the input, background noise, etc. If the list of these characters is available (for example a list of Product IDs or an Order ID) we can train the voice agent on the same using boost phrases.
Can voice agent dynamically understand different languages and if required, switch the language on the fly?
Yes, this can be done using the Auto-Language Detection feature. Currently, this is under Beta. Learn more here.
Why is the voice data different in the Insights and Engage dashboards?
In Engage, there is a 2-5 minute window for checking the status of voice campaign calls. During this time, calls are queued in the voice queue. The status is then sent in the notification report. If the call status remains unchanged after this period, Engage considers the calls as failed to connect and moves the users to the next node. Hence, there might be a mismatch in the data displayed on the Insights vs. Engage dashboards/reports.
---
## Introduction to Conversational Voice AI - Benefits and Applications for Businesses
In this article, you will learn:
1. [Introduction to conversational voice AI](#2-introduction-to-conversational-voice-ai)
2. [Deploying and understanding voice agents for business](#3-deploying-and-understanding-voice-agents-for-business)
3. [Yellow.ai's complete voice agent solution provided by each module](#4-yellowais-complete-voice-bot-solution)
------
## 1. AI Voice agent Demo
:::info
- **Visit our [voice channel](https://yellow.ai/voice-channel/) to listen to the live calls attended by the yellow.ai voice agents.**
- Post your queries on [voice community](https://community.yellow.ai/c/voice/31).
- Contact the platform team for support and pricing details.
:::
## 2. Introduction to conversational voice AI
To begin with, let's understand Conversational AI before delving into its subset, Conversational Voice AI.
### What is conversational AI?
Conversational AI, short for Conversational Artificial Intelligence, refers to the utilization of technology and algorithms to create lifelike dialogues and interactions between humans and machines. By incorporating Natural Language Processing (NLP), Machine Learning (ML), and other related technologies, chat agents, virtual assistants, and other automated systems can communicate with users in a way that is natural and intuitive, similar to how humans converse with one another.
To comprehend user input, conversational AI systems employ various techniques such as speech recognition, text analysis, and semantic understanding, and can tailor their responses to meet the user's needs and business preferences. These systems have a wide range of applications, from customer service and healthcare to education and entertainment, providing personalized support, answering questions, and automating mundane tasks.
****
----
### What is conversational voice AI
Conversational AI is an extensive domain that encompasses diverse channels and technologies. One of its significant subsets is Conversational Voice AI, which focuses specifically on voice-based interactions between machines and humans. It leverages Speech Recognition technologies and Speech Synthesis alongside NLP to enable users to interact with devices and software using natural language or voice commands instead of traditional input methods like typing or clicking.
Conversational Voice AI systems employ speech recognition technologies to convert spoken words into text, enabling NLP algorithms to understand their meaning and provide an appropriate response that can be converted back into voice or audio using speech synthesis. These systems can be integrated into various devices and platforms, including smart speakers, IVR assistants, mobile apps, and cars.
Overall, Conversational Voice AI holds immense potential to improve accessibility and convenience for users, making it easier for them to interact with technology more naturally and intuitively. It can revolutionize the way users interact with devices and software, leading to enhanced user satisfaction and a better user experience.
****
------
### Adapting to customer needs with voice agents
In today's fast-paced world, customer preferences evolve rapidly, and businesses must keep up to stay ahead of the competition and meet their customers' changing needs. Customers increasingly prefer automated self-service options like mobile applications or business chat agent setups to address simple concerns, such as updating personal account details or canceling an order.
While the popularity of automated self-service options is nothing new, customers now seek even more convenience by resolving their queries through voice commands. This is where voice agents come in, providing the ease and convenience customers crave for resolving their queries.
To assist businesses in providing better virtual assistants, Yellow offers voice agents that can help them meet their customers' needs effectively.
----
## 3. Deploying and understanding voice agents for business
Yellow AI offers top-notch voice agents that can be easily integrated with a business's phone lines. These voice agents simulate human-like conversations and can perform various tasks, including answering questions, providing information, and completing transactions.
With voice agents in place, customers can dial a business's phone number and receive quick and convenient solutions to their simpler queries. Additionally, businesses can leverage outbound campaigns via phone calls to reach out to their target audience for tasks such as collecting product feedback, verifying user data, and reminding users of payment deadlines.
Here's how voice agents work end-to-end:
1. The **automatic speech recognition** system listens to the caller's request and transforms it into text.
2. The **natural language understanding** component comprehends the speaker's intent and identifies relevant information to drive the conversation forward.
3. The **conversation module**, or business logic, determines the appropriate response by considering the user's request's context.
4. Advanced **text-to-speech** technology converts the response text into human-like speech.
5. Voice agents continually improve their ability to simulate human conversations by analyzing user data and adding it to their knowledge database using advanced **machine learning** features.
****
-----
## 4. Yellow.ai's Complete Voice Bot Solution
Yellow.ai offers a complete voice agent solution that integrates speech recognition and speech synthesis technologies into their product ecosystem. This comprehensive solution simplifies the process of creating and deploying voice agents for businesses. Let's take a closer look at the different products in the ecosystem.
1. **Design module**: This module provides an intuitive and straightforward way for users to design and craft their own conversations quickly and easily.
2. **Automation module**: Once a conversational voice agent is created, businesses can personalize the experience by connecting it to their CRM and APIs. This module helps businesses to create custom voice agents tailored to their specific needs.
3. **Engage module**: Businesses can use voice agents to reach out to customers via outbound campaigns. The User 360* feature in this module maintains a digital diary of customers and helps to run targeted campaigns.
4. **Insights module**: The Insights module provides businesses with detailed analytics and metrics related to their voice agents performance, such as the number of calls, call duration, and API response time.
5. **Channels module**: Businesses can easily set up their voice agents, including configuring the IVR channel, and associated phone numbers.
6. **Integration module**: Along with leading speech recognition and speech synthesis technologies, businesses can integrate their Voice Bots with other external services like CRM. These integrations can then be utilized in the voice agent flows, making it possible to create a more personalized experience for customers.
---
## How to contact Yellow.ai support
To report any issues or questions regarding the Yellow.ai product.
1. Connect with a live agent using the Mia Support bot
2. Raise a Support Ticket via email
--------
## Connecting with the support team
### 1. Using the Mia Support bot
To get quick answers to your queries:
1. Visit https://help.yellow.ai/. You will find the Mia Support Chatbot at the bottom right corner.
2. Interact with the bot by selecting the **I have a concern** option and entering your query.
****
3. The bot will try to provide a response to your query. If the bot does not have an answer, you can opt to connect with a live agent.
****
------
### 2. Connecting with a Live Agent
To directly connect with a live agent:
1. Visit https://help.yellow.ai/. You will find the Mia Support Chatbot at the bottom right corner.
2. Type **Talk to live agent** in the chatbot.
****
3. Validate your identity by entering your name and email address. Verify your email by entering the OTP sent to your email.
4. Select the bot for which you need assistance.
****
5. A live agent will assist you with your query. If the issue cannot be resolved via chat, the agent will create a support ticket and provide you with a reference case number for tracking.
-------
### 3. Raising a Support Ticket via Email
You can raise a support ticket by emailing the support team at support@yellow.ai.
In your email, include the following details to help the support team debug and resolve your issue promptly:
* Bot ID of the bot
* Flow name
* Steps to replicate the issue
* Relevant screenshots
---
## CRM Integration
Integrate Yellow.ai's Agentic AI platform with your Customer Relationship Management (CRM) systems to provide personalized customer experiences, automate support workflows, and enhance agent productivity.
## Why Integrate with CRM?
- **Personalized Conversations**: Access customer data (e.g., name, order history, support tickets) to tailor bot responses.
- **Automated Lead Qualification**: Qualify leads through bot conversations and automatically create/update lead records in your CRM.
- **Streamlined Support**: Create, update, and retrieve support tickets directly from bot conversations.
- **Agent Empowerment**: Provide human agents with full customer context during handoffs.
## Supported CRM Systems
Yellow.ai offers out-of-the-box integrations and flexible API options for popular CRM platforms, including:
- Salesforce Service Cloud
- HubSpot CRM
- Microsoft Dynamics 365
- Zoho CRM
- And more via custom API integrations.
## Common Integration Use Cases
### 1. Lead Generation & Qualification
- **Bot Action**: Collect user details (name, email, company, query).
- **CRM Action**: Create a new lead record in Salesforce or HubSpot.
- **Bot Response**: Confirm lead creation and provide next steps.
### 2. Support Ticket Management
- **Bot Action**: Identify user intent as a support query.
- **CRM Action**: Search for existing tickets or create a new one in Zendesk or Freshdesk.
- **Bot Response**: Provide ticket status or confirmation.
### 3. Customer Data Retrieval
- **Bot Action**: User asks for order status or account details.
- **CRM Action**: Retrieve relevant data from the CRM using user ID.
- **Bot Response**: Present personalized information to the user.
## Integration Steps (General)
1. **Authentication**: Set up secure authentication (API Key or OAuth 2.0) with your CRM.
2. **Map Data Fields**: Define how data from Yellow.ai conversations maps to fields in your CRM.
3. **Configure Workflows**: Use Yellow.ai's Studio to create flows that trigger CRM actions (e.g., "Create Lead" node, "Update Ticket" API call).
4. **Test & Deploy**: Thoroughly test your integration in a staging environment before deploying to production.
## Further Reading
- [Salesforce Service Cloud Integration](/docs/platform_concepts/appConfiguration/salesforce-service-cloud)
- [HubSpot CRM Integration](/docs/platform_concepts/appConfiguration/hubspot-crm)
- [API Node Documentation](/docs/platform_concepts/studio/build/nodes/action-nodes-overview/api-node)
---
## Integrations for Service Desk & Digital Workplace Place (DWP) Automation
## Introduction
You can integrate enterprise systems such as ITSM, IAM, DEX, and endpoint-management tools to our Agent AI using APIs in the AI Agent Builder.
These integrations allow the AI Agent to:
- Perform operational tasks (for example, reset a device, create a ticket)
- Retrieve contextual data from connected systems
- Trigger automated actions across Service Desk and Digital Workplace (DWP) environments
Each integration setup is modular, API-driven, and can work seamlessly within enterprise ecosystems.
For systems requiring endpoint-level operations, a **Workplace Self-Service Agent** is installed on user devices or environments. This agent acts as the execution layer, enabling remote troubleshooting, script-based actions (e.g., PowerShell), and device management while APIs handle orchestration and control.
## How to Use This Guide
Each API reference in this guide follows a consistent structure to help you easily configure and test APIs within the Automation → API section of your platform.
You can use this documentation to:
- Understand the request type and endpoint required for each integration.
- Identify parameters, headers, and body components to configure the API in the platform.
- Test the API and verify the response directly within the platform’s interface.
## Steps to Configure and Test an API
1. Go to **Automation** > **Build** > **API** and click **+ Add new API**.
2. In the configuration screen:
1. Select the HTTP method (GET, POST, PUT, or DELETE).
2. Enter the API endpoint as shown in this document.
3. Switch to the respective tabs to add the necessary details:
* **Params** tab — Add query or path parameters.
* **Header** tab — Add authorization or content-type headers.
* **Body** tab — Include request body (for POST or PUT APIs).
4. Click **Send** to test the API.
* The system displays an input screen where you can enter dynamic values (e.g., tokens, device IDs) for real-time testing.
* Review the response in the output panel to validate success.
* Once verified, Save the configuration. You can now use this API in Agent AI flows or workflows.
For a detailed guide on how to add APIs, refer to the [Add API Manually](https://docs.yellow.ai/docs/platform_concepts/studio/api/add-api#add-api-manually) guide.
:::note
Ensure you test your API configuration using the built-in API Test Console before linking it with any automation or Agent AI flow.
:::
---
## SysTrack Integration – API Configuration
## Get Access Token
> **Note:** The URL below may vary per customer tenant/environment. Confirm the correct base URL or tenant ID for your setup.
| API Details | Description |
|------|-------------|
| **Endpoint** | `https://systrackcegl.b2clogin.com/systrackcegl.onmicrosoft.com/b2c_1_ropc_auth/oauth2/v2.0/token` |
| **Method** | `POST`
| **Content-Type** | `application/x-www-form-urlencoded` |
| **Form Parameters** | `grant_type`, `response_type`, `username`, `password`, `client_id`, `scope` |
| Parameter | Description
| --------- | ------------
| **grant_type** | Specifies the OAuth 2.0 grant type being used. For the ROPC flow, this value must be set to `password`. **Example:** `password` |
| **response_type** | Defines the type of tokens expected in the response (for example, access token or ID token). Some configurations require both `token` and `id_token`. **Example:** `token id_token` |
| **username** | The end user’s login identifier (such as their email address or UPN) used for authentication. **Example:** `user@company.com` |
| **password** | The password corresponding to the specified username. This value is sent in the request body and should always be handled securely. **Example:** `YourSecurePassword123!` |
| **client_id** | The unique identifier of the registered application in Azure AD B2C. It identifies which client is requesting the token. **Example:** `00000000-aaaa-1111-bbbb-2222cccc3333` |
| **scope** | Specifies the permissions or scopes requested for the access token. It typically includes your API’s scope, along with standard OpenID scopes. **Example:** `https://tenant.onmicrosoft.com/api/read openid offline_access` |
##### Example Request (cURL)
```bash
curl --location --request POST 'https://systrackcegl.b2clogin.com}/systrackcegl.onmicrosoft.com/B2C_1_ROPC_AUTH/oauth2/v2.0/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'response_type=token' \
--data-urlencode 'username=your_user@domain.com' \
--data-urlencode 'password=YourPassword' \
--data-urlencode 'client_id=your_client_id' \
--data-urlencode 'scope=your_scope'
```
## Get Device Details
Retrieves complete details of a specific device in Systrack using its Fully Qualified Domain Name (FQDN).
#### API Endpoint
`GET` `https://{example-tenant}.lakesidesoftware.com/api/systems?$filter=(fqdn eq '{{systrackDevice}}')`
#### Header
Header | Description
------ | -----------
Authorization | The access token obtained from the authentication API. Required for secure access to the SysTrack API. Format: `Bearer {{accessToken}}`
#### Params
Parameter | Description
--------- | -----------
fqdn | The fully qualified domain name of the target device. This parameter filters the system information for the specified device. `fqdn eq '{{systrackDevice}}'`
#### Sample Request
```bash
GET https://{example-tenant}.lakesidesoftware.com/api/systems?$filter=(fqdn eq '{{systrackDevice}}')
Authorization: Bearer {{accessToken}}
```
## Get GUID
Retrieves the GUID (Globally Unique Identifier) of a specific user from the SysTrack environment using their user ID.
#### API Endpoint
```bash
GET https://{example-tenant}.lakesidesoftware.com/api/systems/users?user={{systrackUserId}}
```
#### Header
* **Authorization**: The access token obtained from the authentication API. Required for authorization. *Example*: `Bearer {{token}}`
#### Param
* **user**: The user ID used to retrieve the corresponding GUID from SysTrack. *Example*: `{{systrackUserId}}`
## Get Sensor Actions
Retrieves the list of available sensor actions from the SysTrack environment.
These actions represent system-level operations that can be executed on devices (for example, restarting a process or collecting performance data).
#### API Endpoint
```bash
GET https://{example-tenant}.lakesidesoftware.com/api/sensoractions
```
#### Header
* **Authorization**: The access token obtained from the authentication API. Required for authorization. *Example*: `Bearer {{token}}`
#### Example
```bash
GET https://{example-tenant}.lakesidesoftware.com/api/sensoractions
Authorization: Bearer {{accessToken}}
```
## Get Sensor Issues
Retrieves detailed sensor issue data for a specific system, within a defined time range.
This API helps identify issues identified by SysTrack sensors (for example, CPU spikes, latency, or memory usage).
#### API Endpoint
```bash
GET https://{example-tenant}.lakesidesoftware.com/api/sensors/child/{{sysGuid}}?startTime={{startTime}}&endTime={{endTime}}
```
#### Params
Parameter | Description
--------- | -----------
sysGuid | The system GUID of the device for which sensor data is requested. This can be fetched using the Get GUID API. Example: `123e4567-e89b-12d3-a456-426614174000`
startTime | Start of the time window (in ISO 8601 format) for which sensor data should be fetched.
startTime | End of the time window (in ISO 8601 format) for which sensor data should be fetched.
#### Header
* **Authorization**: The access token obtained from the authentication API. Required for authorization. *Example*: `Bearer {{token}}`
## Run Sensor Action
Executes a predefined sensor action (such as running a diagnostic or remediation task) on one or more systems within your environment.
This API enables automated execution of corrective actions identified through sensor data or monitoring workflows.
#### API Endpoint
```bash
POST https://{example-tenant}.lakesidesoftware.com/api/sensoractions/run
```
#### Header
* **Authorization**: The access token obtained from the authentication API. Required for authorization. *Example*: `Bearer {{token}}`
* **Content-Type**: The format of the request body. Set to JSON.
#### Request Body
```json
# Sample JSON
{
"systems": [
"f2d6e4f9-1ccc-44d3-9dec-1737df2d1bd4"
],
"executePackages": [
{
"profileID": "{{profile}}",
"actionToTake": "1",
"parameters": {}
}
]
}
```
| **Parameter** | **Description** |
| ----------------- | ------------------ |
| `systems` | List of system GUIDs on which the action should be executed. Each system ID can be fetched using the **Get GUID API**. Example: `["f2d6e4f9-1ccc-44d3-9dec-1737df2d1bd4"]`
| `executePackages` | Array defining the action details to be executed. |
| `profileID` | The ID of the sensor action profile to execute. Example: `"Device_Restart_Profile"` |
| `actionToTake` | Specifies the action type or mode to execute. Value `1` usually represents “execute now.” `"1"` |
| `parameters` | Optional input parameters required by the sensor action. Leave empty `{}` if not applicable. |
---
## Advanced Virtual Assistants
Advanced virtual assistants (VAs) process human inputs to execute tasks, deliver predictions and offer decisions. AVAs are powered by a combination of:More advanced user interfaces (3D graphics and multimodal interfaces: gestures, touch, OCR, etc.) NLP (multi-intent recognition, syntactic and semantic-based methods,and speech synthesis) Deep learning techniques (such as deep neural networks [DNNs], decision support and personalization), as well as contextual and domain specific knowledge. In this manner, advanced VAs assist people with more human-like multiturn conversations and automate more complex tasks.
---
## Agent Assist
Agent-assist is an intelligent handoff to live agents used by an AI-powered chatbot or voicebot. Agent-assist improves the efficiency of live agents by quickly providing them context of the query and connecting them to the customer, for efficient resolution
---
## Behaviour Prediction
The ability to predict the behavior of a user based on past interactions or past interactions with others.
---
## Biometric Authentication
The ability to identify and authorize a user based on voice patterns.
---
## Bot Fallback
The ability to fall back to another bot. Typical uses of this is mixing multiple bots in the same system. Like a front bot doing broad intents, deep conversations and transactions — and a bot behind it that can do simple questions and answers
---
## Bot-to-bot Communication Using Natural Language
The ability of the conversational platform to turn requests into new requests that are then used to communicate with other bots
---
## Capability Directory
A directory of services that implement a particular API, one or more of which can be used when the capability is needed.
---
## Chat
Chat is an interface that captures typed dialogue between two or more participants.
---
## Chatbot
A chatbot is a domain-specific conversational interface that uses an app, messaging platform, social network or chat solution for its conversations. They are always narrow in scope and primarily text-based.
---
## Clarifying Dialogue
When faced with multiple possible intents or an intent below the confidence threshold, this is the ability to ask questions that will improve the confidence threshold.
---
## Compound Response Generation
The ability to take several answers and turning them into one compound response.
---
## Confirmational Cues
The ability to (“aha,” “hm,” “huh,” etc.) to express understanding, deal with confusion or guide the user through sound
---
## Contextualization
The ability to make contextual cues part of intent matching. Simple architectures will not consider context when matching.
---
## Conversational AI
AI technology that encompasses conversational agents & natural language technology such as NLP, NLU that enable conversational platforms and are used to build conversational agents.
---
## Conversational History
The ability to learn from previous conversations and reuse that information in future conversations becomes increasingly important as frequency of use increases (such as in virtual assistants and some chatbot use cases).
---
## CPaaS
CPaaS stands for communications platform-as-a-service. It is simply a cloud-based platform. CPaaS lets developers program the entire breadth of real-time, cloud-based communications platforms into their own applications to give customers the best experience available.
---
## CSAT
CSAT (Customer Satisfaction) is a measurement used to quantify the degree to which customers are satisfied with a service, product or experience.
---
## Custom UI
Custom UI components are interface elements you can create for application-specific purposes.
---
## Custom Integration
Custom integration simply means that integration needs to be custom coded for the implementation.
---
## Custom Intent Registry
The ability to train your service in recognizing a particular intent (which can be unknown to the conversational platform), and register that intent, along with the training to recognize it with the conversational platform.
---
## Customer Engagement
Customer engagement is the process of interacting with customers through varied channels to develop and strengthen a relationship with them
---
## Customer Experience Automation
Customer experience (CX) automation is any technology that assists customers with common tasks, sometimes replacing the involvement of humans, to improve customer interactions
---
## Customer Experience
It is the customer’s perceptions and related feelings caused by the one-off and cumulative effect of interactions with a supplier’s employees, systems, channels or products.
---
## Customer Journey
A customer journey is a tool that helps stakeholders understand the series of connected experiences that customers desire and needs — whether that be completing a desired task or traversing the end-to-end journey from prospect to customer to loyal advocate.
---
## Decision Tree Node Integration
The ability to specify a RESTful method call to be executed from a particular node in a decision tree. This allows simple integration from a SaaS-based conversational platform to available RESTful APIs.
---
## Deferred Handling
Instead of just deferring the handling, the whole unprocessed request is passed along to another conversational platform or bot implementation on the same platform. Together with language decomposition, this can enable the handling of complex, general purpose requests by multiple, specific-purpose implementations.
---
## Deferred Intent
After processing and matching intent, the request is passed along to a system that has registered itself to handle that particular intent. The ability to control the conversation, but allows for interchangeable services to execute the requests.
---
## Expression and Behavior Rendering
The ability for agents to add expressions based on context, such as idle movements, waiting, anticipation, nodding and other feedback cues.
---
## Full-Duplex Handling
The ability to understand what the user is saying before the user is finished is important for voice. It allows for corrective statements, clarifying questions, interruptions and confirmational cues in a fashion that’s more natural for users.
---
## Human Fallback
The ability to pass along requests to a human, who then takes over the conversation.
---
## Human-to-Bot Handover
The ability to pass along requests to a human, who then takes over the conversation.
---
## Hyper Automation
Hyperautomation involves the orchestrated use of multiple technologies, tools or platforms, including - AI, ML, RPA, BPM, iPAAS, Low-code/no-code
---
## Integration Platform
A third-party or custom integration platform may be enabled to ease the consumption of APIs and the managing of integrations. If there’s a need to integrate many back-end systems, this might be a necessary capability.
---
## Intent Marketplace
A intent marketplace enables you to pick multiple intent libraries, and to modify them to your needs.
---
## Intermediary Dialogue
The ability to respond like a human when responses are delayed by few seconds, avoiding awkward gaps of silence in the dialogue and help mitigate latency problems.
---
## Keyword or Phrase Matching
Integration through registering a keyword or phrase that, when employed a user, triggers deferring of the handling to the service. An example would be, “Tell Spotify to play some Christmas music.”
---
## Knowledge Extraction
The ability to turn a request into a query. The relevant information is extracted out of a large knowledge or content repository (or multiple), and presented back to the user as an answer. Similar to knowledge mapping, except there is no manual work to map between intents and where the information is. Knowledge extraction can both be a preprocess — where knowledge is ingested and turned into question and answer pairs for internal representation, or it can be done at intervals and even runtime, depending on implementation.
---
## Language Decomposition
The ability to decompose complex requests into simpler separate statements, which are then run as separate requests to different handlers. This would require the ability to compound answers in the response generation. For each type of handling supported, the amount of work involved and the toolsets to do that work should be evaluated.
---
## Knowledge Mapping
The ability to decompose complex requests into simpler separate statements, which are then run as separate requests to different handlers. This would require the ability to compound answers in the response generation. For each type of handling supported, the amount of work involved and the toolsets to do that work should be evaluated.
---
## Language Detection
The ability to detect what language is spoken and automatically switch to an engine supporting that language. In many cases, language has to be explicitly set either by the user or in the configuration of the platform.
---
## Language Support
The ability to handle interactions in particular languages. Support for languages needs to be evaluated on quality, because variants, dialects, slang and accents are all capable of confusing the STT engine.
---
## Language Variant
The ability to handle interactions in different variants or dialects of the same language — for example, French and Canadian French, Norwegian Bokmål and Norwegian Nynorsk, or formal and casual Japanese.
---
## Modality Switching
Instead of answering in the conversation, the ability to direct the user to an appropriate service, app or website where the request can be fulfilled.
---
## Multimodal Capabilities
Multimodal capabilities allow VAs to combine use inputs via text, voice and touch (on a screen) with ability to process data from various data sources beyond just text, like images, video, tables, maps, etc.
---
## Multimodal Rendering
The capability to reply in chat or voice, as well as render other means that add to the exchange of information. This could be simple body language rendered on a virtual agent or expressions by a physical robotic assistant
---
## Natural Language Generation (NLG)
The ability to generate natural language responses, based on structured data or other inputs. NLG is important if there are handling methods other than decision trees.
---
## Omnichannel
The consistency and synergy across channels—mobile, desktop, and store—to support the purchase process from discovery to conversion, along with fulfillment and postpurchase.
---
## Orchestration
Chatbot orchestration lets users talk to only one main bot - that can internally refer to several child bots and uses a recommendation engine to suggest the most relevant responses.
---
## Parked Intents
This is the ability to recognize when a user asks for something different in the middle of a dialogue.
---
## Personalization
The ability to tailor the personality to the current implementations and to take into account the writing or speaking style of the user, cultural cues and other factors, to personalize the response to an individual user.
---
## Pinpoint Improvements
The ability to pinpoint potential areas for improvement — typically similar requests that are not being handled and similar answers given by human employees on fallback.
---
## Pretrained Intents
A library of intents and the ability to recognize them for a particular use case or domain.
---
## Proactive Conversations
The ability of conversational platforms to initiate conversations, instead of only responding to users.
---
## Process Mapping
The ability to map conversations into steps in business processes, focusing the conversational elements on what is “current state” and what information or action is needed to move to the next step in the process
---
## Propose Improvements
The ability to monitor and propose new additions to the decision trees or other handlers. It often involves ML to give proposals and human supervision to approve them.
---
## Quality Assurance
The ability to ensure consistent quality, as the implementation scales. This includes monitoring the quality of intent matching, so training phrases that would make performance deteriorate would be flagged.
---
## Reinforcement Learning
Reinforcement learning (RL) is a type of machine learning where the learning system receives training only in terms of rewards and punishments. It then attempts to foster actions or situations for which the overall reward is maximized and the punishments are minimized.
---
## Rich Communication Service
Rich Communication Services is a communication protocol between mobile-telephone carriers and between phone and carrier, aiming at replacing SMS messages with a text-message system that is richer. Some examples are Google Business Messages, RCS Messaging
:::note
RCS channel is currently unavailable on our platform. Please raise a feature request if you need this channel.
:::
---
## Script Generation
The ability to translate output from the processing step into a more-formalized scripting language that is executed in a script engine. The script engine could enable other handling mechanisms and direct integrations.
---
## Search and Summarization
The ability to take the phrase written by the user and turns it into a search query to run against one or more knowledge repositories
---
## Search
The capability of passing along the request to a search engine that will present the user with search results
---
## Second/Third Party User Data
The ability to leverage outside data about the user. For example, it can take the form of CRM data or information from a public profile on Facebook.
---
## Self-service Routing
Routes to the appropriate self-service system, like a ticket system.
---
## Sentence Rewriting
Parses phrases and modifies them before they are processed again for intent. This is a way to handle common challenges, such as misspellings, slang, synonyms or even sentence structures (e.g., double negatives).
---
## Sentiment Analysis
Categorizes and identifies opinions expressed in the phrases the user is writing and attempts to derive the user’s attitude toward topics, products or services.
---
## Small Talk Handling
The ability to gracefully deal with small talk attempts by the user, like talking about the weather or common greetings, such as, “How are you doing today?”
---
## Supervised Learning Loop
An interface to easily map missed intents to what the engine should have originally responded.
---
## Text to Speech (TTS)
The ability to generate audible voice by the platform
---
## Total Experience Automation
Total Experience (TX) is a strategy that creates superior shared experiences by interlinking the multiexperience (MX), customer experience (CX), employee experience (EX) and user experience (UX) disciplines
---
## Virtual Assistant
VAs are a conversational interface that uses semantic and deep learning (such as DNNs, natural language processing, prediction models, recommendations and personalization) to assist people or automate tasks. VAs can be deployed in several use cases, including virtual personal assistants, virtual customer assistants and virtual employee assistants.
---
## Voice Only
The ability to handle all interactions using voice without ever falling back on presenting rich output, such as search result lists, pictures and maps that require a screen.
---
## Voice Synthesis
The ability to generate humanlike voice, advanced functionality would be multiple voices, variances of incantation based on context and support for multiple languages.
---
## Inbox Ticketing API
A public REST API for managing Inbox tickets programmatically — create and update
tickets, post public replies and internal notes, assign to agents or groups,
manage tags and attachments, list custom views, and search tickets.
:::info Early access
This API is in early access. Reach out to our team to get access.
:::
## Base URL
All endpoints are served under:
```
https:///api/agents/public/v1
```
`` is your region's platform host (for example `cloud.yellow.ai`).
## Authentication
Every request must send an API key and target a bot:
- **Header** — `x-api-key: `
- **Query** — `?bot=` (required on every endpoint)
The key is resolved to a user, who must hold an agent/admin role on the target
bot. Requests with a missing/invalid key — or for a bot the key has no access to —
are rejected with `401`. These endpoints accept API-key auth only (dashboard
session cookies are not accepted).
All failures return a JSON error body of the form:
```json
{ "error": "human-readable message" }
```
## Response & status codes
| Code | Meaning |
|------|---------|
| `200` | Success — also returned by create when an active ticket already exists |
| `201` | Ticket created |
| `400` | Invalid request (validation failed — see the message) |
| `401` | Missing/invalid API key, no role on the bot, or the feature is not enabled |
| `404` | Ticket (or referenced agent) not found |
| `422` | Unsupported ticket status transition |
| `500` | Internal error |
## Conventions
### Requester identity
A ticket is created for a **requester** identified by one of `email`, `phone`, or
`external_id` (the first present becomes the contact's uid). `email` and `phone`
are format-validated.
### Source
`source` is **required** on create — it identifies the origin channel. Allowed
values:
`whatsapp`, `facebook`, `yellowmessenger`, `appleBusinessChat`, `email`,
`lazada`, `instagram`.
### Priority
`low`, `normal`, `high`, and `urgent` are accepted and mapped to `LOW` / `MEDIUM`
/ `HIGH` (`normal` → `MEDIUM`, `urgent` → `HIGH`). Defaults to `MEDIUM`.
### Ticket status transitions
On `PUT /tickets/{id}`, the `status` field accepts:
- `solved` or `closed` → resolves the ticket.
- `open` → **reopens** it. Reopening creates a **new** ticket linked to the
original and returns both: `{ "ticket": , "previousTicketId": }`.
- Any other value → `422`.
### Custom fields
`customFields` must be a key-value object (for example `{ "plan": "enterprise" }`).
Keys must be configured in the bot's support settings; unknown keys are rejected
with `400`.
### Pagination
List, search, and message endpoints return up to **100** items per page. Pass
`?page=` (0-based). Responses include `total`, `count`, and `next_page` /
`previous_page` (either may be `null`).
### Search query
`GET /ticket/search` accepts a compact `query` string:
- `type:ticket` — no-op (only tickets are returned).
- `status:` — exact status match.
- `status<` — every status ordered before `` in the ticket
lifecycle: `INITIAL` → `QUEUED` → `OPEN` → `ASSIGNED` → `WRAP-UP` → `RESOLVED`
→ `MISSED`.
Example: `type:ticket status/api/agents/public/v1/tickets?bot=' \
-H 'x-api-key: ' \
-H 'Content-Type: application/json' \
-d '{
"requester": { "email": "jane@example.com", "name": "Jane Doe" },
"source": "yellowmessenger",
"subject": "Unable to log in",
"priority": "normal",
"tags": ["login"]
}'
```
A new ticket returns `201`; if the requester already has an active ticket, that
one is returned with `200` (no duplicate is created).
## Endpoints
| Method | Purpose | Reference |
|--------|---------|-----------|
| `POST` | Create (or find an existing) ticket | [Create a ticket](/api/create-a-ticket) |
| `PUT` | Update a ticket — status, comment, assignment, tags, custom fields | [Update a ticket](/api/update-a-ticket) |
| `GET` | List a ticket's messages (paginated) | [List ticket messages](/api/list-ticket-messages) |
| `POST` | Upload and attach a file | [Upload an attachment](/api/upload-an-attachment) |
| `PUT` | Replace a ticket's tags | [Replace ticket tags](/api/replace-ticket-tags) |
| `DELETE` | Remove tags from a ticket | [Remove ticket tags](/api/remove-ticket-tags) |
| `GET` | List custom views | [List custom views](/api/list-custom-views) |
| `GET` | List tickets in a view (paginated) | [List tickets in a view](/api/list-tickets-in-a-view) |
| `GET` | Search tickets | [Search tickets](/api/search-tickets) |
### Endpoint notes
- **Create a ticket** — create-or-find; requires `source`; validates
email/phone/priority and rejects unknown custom-field keys.
- **Update a ticket** — send one intent per request: `status`, `comment`
(`{ "body", "public" }` — `public: false` posts an internal note),
`category`/`group_id`, `assignedTo`/`assignee_id`, `customFields`, or `tags`.
- **List ticket messages** — paginated (`?page=`, see Pagination above,
newest page first). `?sort_order=asc` (oldest first within a page, default)
or `desc`. Internal notes are returned with `public: false`.
- **Upload an attachment** — `multipart/form-data` with a single field named
`file` (max 25 MB).
- **Tags** — `PUT` replaces the full tag set; `DELETE` removes the listed tags.
The body is `{ "tags": [ ... ] }` (must be an array).
---
## Best Practices for Build a VoiceX AI Agent
## Managing Latency in VoiceX Conversations
The average voice-to-voice latency (time between the user’s last word and the bot’s first word) in a VoiceX conversation is approximately **1.5 seconds**. Below is the latency breakdown:
- **Final Silence Duration**: 200 ms
- **STT (Speech-to-Text) Transcription**: 0 - 300 ms
- **Platform Latency / LLM First Sentence**: 1 - 1.5 s
- **TTS (Text-to-Speech) Time to First Chunk**: 0 - 1 s
- **Total Latency**: **1.5 - 2.7 s**
> If latency exceeds **1.5 - 2.7 seconds** for multiple turns, raise a **DevRev ticket**.
## Enabling Interruptions
Enable **Interruptions** in **Dynamic Chat node > Voice Configuration** to utilize the latest interruption handling mechanism. Ensure the **Final Silence Duration** is set to **0.2 seconds**.
## Improving Speech Recognition Accuracy with Boost Phrases
Use **Boost Phrases** to enhance recognition accuracy for industry-specific jargon, technical terms, regional definitions, and locations. There are two ways to pass Boost Phrases:
1. **In the Question/Text Node**
- Pass a predefined list of boost phrases in the node configuration.
- Alternatively, use a function to dynamically generate an array of boost phrases and pass them via **custom voice options** under the `boost_phrases` key.
2. **In the Dynamic Chat (DC) Node**
- A fixed set of words and phrases can be passed via **Dynamic Node > Voice Configuration > Boost Phrases**.
## Knowledge Base (KB) Integration
Knowledge Base searching is now available in VoiceX conversations via **Skills**. You can either:
- Create a dedicated **KB skill**, or
- Enable **document search** within an existing skill.
### Reducing User-Perceived Latency
To minimize user frustration during the KB search wait time, use the following techniques:
1. **Acknowledge the request with preemptive messages**. These messages will play in parallel to the KB search function, reducing perceived wait time by **1-3 seconds**. Examples:
- *“Hold on, let me fetch it for you.”*
- *“Give me a moment to check this.”*
2. **Set expectations upfront with conversational fillers**. These create a smoother, more human-like interaction, reducing frustration during brief wait periods. Examples:
- *“This might take a few seconds, hang tight!”*
- *“Give me some time, I’m fetching it for you.”*
- *“Please wait, I’m finding the best answer.”*
:::note
KB responses take **7-15 seconds** to generate. Efforts are underway to reduce this latency.
:::
:::info
Learn about Dynamic chat node in detail [here](https://docs.yellow.ai/docs/platform_concepts/studio/dynamicchatnode).
:::
---
## Set Up VoiceX AI Agent
## Steps to Set Up VoiceX AI Agent
Follow these guidelines to develop a VoiceX conversational AI agent.
### 1. Create a Bot
1. Open the bot templates and click **+ Create from Scratch** (**+ Create AI Agent** does not support voice).
2. Enter the bot details and select the correct region. Choosing the right region is crucial for optimal server performance, reducing latency, and attaching appropriate phone numbers.
3. Click **Create bot**.
### 2. Map to an IVR Phone Number
The bot must be hosted on a specific server. Contact support with your **Bot ID** and **Region Details** to request hosting. The support team will assign a phone number based on the bot's hosting location.
For development purposes, request a number mapped to one of the available servers.
#### Deploy on Yellow.ai Server
On Yellow.ai Slack support channels, ping **#voice-support** to request a new number mapped to your bot. You can also request custom voice options to be enabled in the same **#voice-support** request.
> Currently, VoiceX bots are deployed only on select Yellow.ai-owned servers (**voice-deployments**) in the following regions:
> - **India**
> - **USA**
> - **Indonesia**
#### Deploy on Your Own Server
If you have a separate deployment, you can easily host the bot on your setup. Raise a **DevRev ticket** to Voice Support for assistance.
:::info
#### Verify the Server Connection
To ensure the call is routed through the correct server:
1. Go to **Conversation Logs**.
2. Check **Welcome Message Logs**.
3. Look for **"machine_id"** – it should match one of the supported deployments.
:::
To view the list of enabled IVR numbers for each region, navigate to **Channels > IVR**.
### 3. Build the VoiceX Flow
When creating a VoiceX bot, certain steps must be followed for the **initial (welcome) flow**. This includes adding a **Question/Text Node** first and using a **Dynamic Chat Node** with the required **configurations**.
#### Build the Flow
1. Navigate to **Flows > Create Flow from Scratch**.
2. In the **Start Node**, attach either:
- A **Question Node** (preferred for user interactions).
- A **Text Node** (for playing a statement before initiating the flow).
This can be used for welcome messages or disclaimers. Example:
- `"Hi, this is YYZ Bot. I will help you with your flight bookings. What would you like to start with?"`
- `"Hi, your call will be recorded for training purposes."`
⚠️ **Avoid entering the conversational prompt in the Question Node**, as it may cause potential issues.
### 4. Configure Speech-to-Text (STT)
To set up STT, go to:
**Question/Text Node > Settings > Voice > STT** and configure the following:
- **STT Engine**: Set to `Microsoft`.
- **STT Mode**: Select `"Streaming 2.0 Plus (Beta)"`.
- **Recording Max Duration**: Set to `≥ 15 seconds` to accommodate longer user responses.
- **Initial Silence Duration**: Set to `≥ 7 seconds` to give users enough time to respond.
- **Final Silence Duration**: Set to `0.2 seconds`. This can be adjusted for specific Question/Text nodes if needed.
- **STT Language**: Enter the appropriate **language code** based on your target audience.
- Full list of Microsoft language codes: [here](https://learn.microsoft.com/en-us/azure/ai-services/speech-service/language-support?tabs=stt).
:::note
Only **English and Hindi** have been thoroughly tested. If you experience issues with other languages, contact the **product team**.
:::
### 5. Configure Text-to-Speech (TTS)
Currently, **Microsoft Azure, Amazon Polly,** and **Eleven Labs** TTS services are supported.
#### **Microsoft Azure TTS Configuration**
- **TTS Engine** – `"Microsoft"`
- **Text Type** – `"Text"`
- **Voice ID** – `"hi-IN-KavyaNeural"`, `"en-US-BrianNeural"`, etc.
- List of available voices: [here](https://learn.microsoft.com/en-us/azure/ai-services/speech-service/language-support?tabs=tts).
#### **Amazon Polly TTS Configuration**
- **TTS Engine** – `"Polly (Amazon)"`
- **Text Type** – `"Text"`
- **Voice ID** – `"Kajal"`, etc.
- List of available voices: [here](https://docs.aws.amazon.com/polly/latest/dg/available-voices.html).
#### **Eleven Labs TTS Configuration**
Default configuration is not available for Eleven Labs.
##### **Step 1**: Use **custom voice options** as mentioned in the **ElevenLabsObject** variable.
**Add Required Variables**
Create the following **variables** (using any custom name):
- **Boolean_True**: Boolean data type with **Value = True**.
- **ElevenLabsObject**: Object data type for **ElevenLabs TTS**. (Skip this step if using another TTS provider). Use the following default object:
```json
{
"engineName": "elevenlabs",
"bodyParams": {
"voiceId": "0ZOhGcBopt9S6GBK8tnj",
"similarity_boost": 0.75,
"stability": 0.5,
"style": 0.75,
"use_speaker_boost": true,
"model_id": "eleven_turbo_v2_5",
"optimize_streaming_latency": 3
}
}
```
> **VoiceID**: Specifies the voice the bot will use. To configure this, select a voice from the ElevenLabs portal and share the voice name with the Voice Support team to get the Voice ID.
**Video Guide: Creating Variables**
**Add Key-Value Pairs**
1. Open the **Question/Text Node** and navigate to **Settings > Voice > Advanced Custom Voice Options > Key-Value Pair**.
2. Add the following key-value pairs:
- **enforce_same_tts** : `Boolean_True`
- **custom_tts** : `ElevenLabsObject`
:::note
If the **Custom Voice Options** are not visible in the **Question/Text Node** settings, contact the **#voice-support** team on Slack to get them enabled.
:::
**Step 2**: Set the **Voice ID** by selecting a voice from the Eleven Labs portal and sharing it with the **Voice Support Team**.
### 6. Connect to Execute Flow
1. Create new flows using the **Dynamic Chat Node**.
2. Connect the **Question/Text Node** to the **Execute Flow Node** and select the next flow to continue the call.
### 7. Build Flows Using Dynamic Chat Node
Create new flows from scratch using the **Dynamic Chat Node**.
:::info
Refer to this document for sample prompts to add in Dynamic chat node: [VoiceX Prompts](platform_concepts/VoiceX/voiceXPrompts.md).
:::
### 8. Debug/Test your VoiceX AI Agent
You can test your bot using the following methods:
#### Using Google Meet
If you have a Google account but cannot call the IVR phone number (e.g., due to ISD or roaming restrictions), follow these steps:
1. Copy your IVR phone number.
2. Open **Google Meet**.
3. Go to **Add people** > **Call**.
4. Paste the IVR phone number and initiate the call.
#### Direct Phone Call
Simply make a phone call to your IVR phone number. The AI agent will respond.
#### Testing & Debugging
- Have a conversation with the AI agent and modify its functionality as needed.
- If the call is connected, you can view the ongoing chat transcript in the **Analyze** module under the **Conversation Log** section.
- Review and refine the AI agent’s responses based on the Conversation logs.
-------
## Upcoming enhancements
1. Improved handling of short and long pauses during user speech.
2. Sentiment analysis for better contextual understanding.
3. Faster execution of VoiceX KB interactions.
4. Natural backchannel responses from both the bot and users for smoother conversations.
---
## The Next Generation of Human-Like Voice AI for Enterprises
> [Try it yourself!](https://yellow.ai/voicex/)
VoiceX is the most advanced, human-like Voice AI platform designed for enterprises to deliver seamless, real-time customer conversations. Powered by **SmoothTalk AI** and **Sentiment AI**, VoiceX eliminates robotic interactions, awkward pauses, and delays, ensuring fluid, natural dialogues that feel authentically human.
Unlike traditional voice bots, VoiceX sets a new benchmark in AI-driven customer engagement by handling complex queries, detecting customer sentiment, and providing accurate responses with ultra-low latency. This makes it an ideal solution for industries such as **BFSI, healthcare, utilities, and retail**.
With VoiceX, enterprises can achieve:
- **60% increase in customer engagement**
- **40% improvement in CSAT (Customer Satisfaction Score)**
- **60% reduction in operational costs**
VoiceX is the AI that talks like **you.**
---
## Challenges with Traditional Voice AI
Current Voice AI solutions in the market face several limitations that hinder the customer experience:
1. **Robotic or unnatural voice interactions** that lack human-like quality.
2. **Lack of conversational intelligence** – inability to guide users smoothly through interactions.
3. **Limited voice intelligence** – poor context awareness, rigid responses, and weak adaptability to conversational styles.
4. **Cumbersome navigation** through multiple menu options.
5. **Inability to handle complex queries** with accuracy.
6. **Abrupt speech interruption** and lack of sentiment judgment, leading to frustrating interactions.
---
## VoiceX 2.0: A New Standard in AI-Powered Conversations
With **Yellow.ai’s VoiceX**, we have completely optimized our infrastructure to support **seamless, natural AI conversations** without interruptions or awkward pauses. VoiceX is for:
- **Enterprises**: Businesses looking to automate customer interactions for support, sales, and engagement.
- **Service Providers**: BFSI, healthcare, retail, and telecom companies requiring high-quality AI-driven interactions.
**Key Innovations:**
- **Tagging & Sentiment Analysis** – Deciphers customer emotions, detects intent, and flags complex queries.
- **Ultra-low latency AI interactions** – Ensuring human-like responsiveness.
- **Context-aware conversations** – Keeps track of past interactions for fluid exchanges.
---
## Key Features
### Voice Intelligence
**Proprietary voice-intelligent algorithm** that refines conversations and significantly reduces latency.
- **Turn-Taking Understanding**: Accurately detects when users finish speaking.
- **AI Agent Backchanneling**: Uses cues like “hmm,” “got it,” to encourage natural conversations.
- **Contextual Interruptibility**: Seamlessly handles user interruptions.
### SmoothTalk AI
Powered by **LLM intelligence**, VoiceX listens smarter, understands hesitations, and responds naturally.
- **More Human-Like Interactions**: Eliminates robotic interruptions.
- **Enhanced Accuracy & Relevance**: Provides precise, contextual responses.
- **Reduces Frustration & Repetitions**: No need for users to repeat themselves.
### Sentiment AI
Real-time sentiment tagging to analyze emotions and optimize customer support.
- **Enhanced Personalization**: Detects frustration, happiness, confusion, and adjusts responses accordingly.
- **Proactive Issue Resolution**: Flags negative sentiment early for human intervention.
- **Data-Driven Decision Making**: Provides insights to refine customer service strategies.
### Acknowledgement AI
Uses **smart verbal cues** (“hmm,” “aha,” “okay,” etc.) to create a **natural conversational rhythm.**
- **Eliminates Awkward Silences**.
- **Boosts User Confidence**.
- **Optimizes Call Flow for Efficiency**.
### Speech Synthesis
- Converts text into **human-like, natural speech**.
### Advanced Language Processing
- **Understands Intent & Context** for accurate responses.
- **Supports Multilingual Conversations** for global engagement.
- **Reduces Misinterpretation** to enhance communication clarity.
---
## Key Benefits
1. **Context-Aware Responses** – Recognizes past interactions, sentiment, and intent for personalized responses.
2. **Seamless Conversations** – AI listens smarter, responds at the right moment, and eliminates awkward pauses.
3. **Effortless Scalability & Efficiency** – Handles high query volumes while freeing up human agents for complex tasks.
4. **Boosts Retention & Loyalty** – Maintains conversational context across multiple channels (Voice, Text, Email, Live Chat, etc.), creating a connected journey.
---
## Use Cases
- **Customer Support**: Automates & streamlines customer queries and resolutions.
- **Sales & Lead Generation**: Engages prospects and captures leads through conversational AI.
- **Appointment Scheduling**: Facilitates seamless booking and management.
- **Feedback Collection**: Gathers customer insights efficiently.
- **Order Management**: Assists with placing, tracking, and managing orders.
- **Sentiment-Aware Support**: Uses real-time tagging & sentiment analysis for empathetic responses.
- **Complex Query Handling**: Processes multi-turn, detailed conversations.
- **Seamless Voice Transactions**: Captures alphanumeric inputs and verifies data accurately.
- **Smart Call Routing**: Tags complex inquiries and routes them to human agents efficiently.
> VoiceX is not just another Voice AI—it’s the AI **that talks like you!**
---
## Sample VoiceX prompts
Below are sample **VoiceX prompts** that can be used in a **Dynamic Chat Node** for reference:
IT Support
```
You are a female customer IT support voice AI agent named Sally and you work for a company called Yellow IT. Your goal is to help users with IT issues related to their keyboard or mouse over a voice call.
Steps to help the user debug the issue:
STEP 1: Greetings and Get the user's full name
Collect the user's name. If the user asks for a reason for sharing their name, mention that this is a required step for internal logging. Example: "Hello, I am Sally from Yellow IT support. I can help you resolve your issues related to IT equipment like keyboard and mouse. Can you please share your name to get started?"
STEP 2: Get the user's mobile number
Collect the user's mobile number. For your internal validation, a valid phone number is 10 digits. Do not mention internal validation rules to the user. If the user asks for a reason for sharing their phone number, mention that this is a required step for internal logging.
STEP 3: Identify if the issue is with Mouse or Keyboard
Once you get the information from the user, ask which product they need help with keyboard or mouse.
If the issue is with the mouse, go to STEP 4.
STEP 4: Check the type of mouse
Check if the mouse the user is using is wired or wireless.
If the issue is with a wireless mouse, go to STEP 5.
STEP 5: Understand the issue the user is facing
Ask, "What kind of issue are you facing with your mouse? Is it related to cosmetic damage, connection issues, buttons not working, batteries, scrolling wheel stuck, or something else?"
If the issue is related to connection issues (connecting to the PC), go to STEP 6.
STEP 6: Check if the user is connecting the mouse for the first time
Ask, "Is this the first time you are connecting the mouse?"
If this isn't the first time the user is connecting the mouse, go to STEP 7.
STEP 7: Recheck the connection to the port
Ask, "Can you try switching the port on the computer where the mouse receiver is connected? Sometimes, there might be an issue with the port of the device as well."
If this still doesn't help, go to STEP 8.
STEP 8: Check the power status of the mouse
Ask, "Is the red power light on the bottom of the mouse turned on or off? If it's not turned on, please check the power switch and turn on the mouse."
If the power status is perfectly fine, go to STEP 9.
STEP 9: Check the type of battery source
Ask, "Is it a rechargeable mouse or does it come with user-replaceable batteries?"
STEP 10: Suggest charging the mouse
For a rechargeable mouse, suggest, "Make sure it is charged for 2 hours once every month." For user-replaceable batteries, suggest, "Make sure they are replaced every 6 months."
If even after replacing the batteries or charging the mouse the issue persists, go to STEP 11.
STEP 11: Check if the mouse works with an alternate laptop or computer
Ask, "Can you try the complete mouse setup with an alternate laptop or computer? If it works with the alternate computer setup, then the issue may be related to the mouse driver file on the personal computer."
If it works with the alternate laptop or computer, go to STEP 12. If not, go to STEP 13.
STEP 12: Share the link to the new driver file for the mouse via SMS
Mention, "I will send you a link to the updated driver file via SMS. Please download and install the latest driver, and then the mouse should start working again. The link can only be sent via SMS and not on any other channel. Alternatively, you can visit the Yellow IT website and download the appropriate driver file from there as well."
STEP 13: Issue needs to be checked with a human agent
Let the user know, "This issue will require assistance from a human agent. Is it fine to transfer the call to an agent?" Once the user agrees to transfer the call to an agent, ask them for the model name of the mouse and how old it is so the agent can better assist.
Rules for having a conversation over the voice channel:
- This conversation is over a voice bot, so use filler words if necessary.
- Answer briefly. Your response should not exceed 300 characters.
- Since the conversation is over a voice channel, the user might interrupt the bot. You can identify the interrupt tag alongside the user's response.
If you determine the user's response is an interruption, you can take one of the following actions:
(a) Acknowledge the user's interruption with some filler words like "Got it," "Understood," "I see," and then transition smoothly with the next response: "Got it. Understood. Now, as I was saying..."
(b) Restate or summarize what the user mentioned just for clarity. Do this only for complex or long user queries.
(c) Be empathetic to the user's query over the interruption.
If the user's message is "#not-speaking," it means the user hasn't responded. Please confirm with the user by asking, "Are you still there?" or "Are you there?"
- If the user's message is "#not-speaking," it means the user hasn't responded. Please confirm with the user by asking, "Are you still there?" or "Are you there?"
- When you think the conversation is over, add `[hangup]` the end of the reply
- When user sends "#callhangup" only then you need to summarise user interaction and add `#[summary:{
"isUserSatisfied":""
}]` to the reply. Summary value is in string format, if user hasn't responded to any format then set value as "NA"
```
Dental Booking
```
You are a female voice AI agent named Sally who is a receptionist for Yellow Dental Clinic owned by Dr. Sonali Patel. Your goal is to assist users in booking dental appointments at Yellow Dental Clinic. Your tasks include gathering necessary information, providing details about available services, and confirming appointments.
### Additional Context,
- Current Month :: July 2024.
- Slots available for booking,
a) Tuesday:: 2 pm to 4 pm
b) Wednesday:: 3 pm to 6 pm
c) Thursday:: 1 pm to 3 pm
d) Friday:: 11 am to 1 pm
- Rough Costs for Treatment,
a) Regular Checkup :: $200
b) Cosmetic Fillings :: $450
c) Tooth or Dental Cleaning :: $300
d) Root Canal Therapy :: $520
e) Anything else :: Dentist will check and confirm
### Name of the dentist - Dr. Sonali Patel, Female
Key Guidelines:
STEP 1: Greetings and Getting the User's Full Name
- Greet the user and introduce yourself.
- Collect the user's name. If the user asks why their name is needed, explain that it is required for internal logging.
Example: "Hello, I am Sally from Yellow Dental Clinic of Dr. Sonali. I can help you book an appointment or with any other general queries. Can you please share your name to get started?"
STEP 2: Getting the User's Mobile Number
- Collect the user's mobile number. Ensure the number is valid (10 digits) but do not mention the validation rule to the user.
- If the user asks why their phone number is needed, explain that it is required for internal logging.
STEP 3: Understand if the user is a new patient or a regular patient.
- Confirm if the user is a new or returning patient. A patient is a new patient if they have not visited in last 10 months. (don't mention this rule to the user unless specifically asked). In case the user is a new patient then greet them well and do ask - how did they heard about our dental clinic.
STEP 4: Providing Service Information
- If requested, provide brief details about the available dental services like Dental Cleaning, Cosmetic Fillings, Regular checkups, Root canal therapy, Toothache, or anything else.
- Confirm if there are any special requests or additional information needed.
STEP 5: Finalizing the Appointment Slot
- If dental cleaning or a regular checkup is required ; it takes around 30 minutes
- For everything else (like root canal or fillings) ; it takes around 60 minutes or 1 hour.
- Ask for the preferred date and time for the appointment.
- If the user requested slot isn't available - Present the available slot to the user in simple language.
STEP 6: Inform the user of any preparation before the clinic visit.
- If they are returning user should always bring their previous dental records.
- If they are new user, request them to bring if they have any prior dental records.
- Inform the user that they should always arrive 15 minutes early for registration.
STEP 7: Closing the call and confirming the appointment
- Recap the appointment details including date, time, and service booked.
Thank the user and let them know that they can reach out in case of any further requirements.
Rules for Having a Conversation Over Voice Channel:
- This conversation is over a voice bot, so use filler words if necessary.
- Keep responses short; your response should not exceed more than 300 characters.
- Once the goal of conversation is completed OR when you think the conversation is over and user don't have any additional queries, add `[hangup]` to the end of the reply
- Since the conversation is happening over a voice channel, the user might interrupt the bot. You can identify the interrupt tag alongside the user's response.
- If you determine the user's response is an interruption, you can take one of the following actions:
(a) Acknowledge the user's interruption with some filler words like "Got it", "Understood", "I see" and then transition smoothly to the next response: "Got it. Now, as I was saying..."
(b) Restate or summarize what the user mentioned for clarity, but only for complex or long user queries.
(c) Be empathetic to the user's query or interruption.
- If the user's message is "#not-speaking," it means the user hasn't responded. Please confirm with the user by asking "Are you still around?" or "Are you there?"
```
Travel Experience Feedback
```
You are a friendly and conversational voice ai female bot named Sally who works for Yellow Travels. Your goal is to collect detailed feedback from travellers about their latest trips and try to upsell services by providing several lucrative offers at the end of the conversation. Keep questions concise and to the point, use the traveller's name to personalize the experience, and confirm understanding after key responses with simple acknowledgements like "Got it" or "Okay." If a user reports an issue, be empathetic and ask relevant questions to better understand the problem before moving ahead.
Additional Context,
- Current Month :: July 2024.
- User Context,
a) Traveller's Name - Alex Carry
b) Last Trip Destination - Singapore
c) Total trip days - 9 days
d) Trip Type - Friends. 5 friends went on the trip.
d) Services used - [Airport pick up and drop, Flight booking, Hotel booking, Site seeing car rental, Food - all 3 meals]
e) Additional note from the user's ticket - the user has requested a refund for 1 day's meal due to the unavailability of lunch.
Detailed step-wise instructions for collecting detailed feedback from the user,
STEP 1) Greetings and check if it's a good time to talk to share feedback related to the previous trip.
Example: "Hi [Traveller's Name], I'm your travel assistant from yellow travels. I am here to gather your valuable feedback on your recent trip. It'll only take a few minutes, and your input helps us improve your travel experiences."
STEP 2) Collect overall feedback with a personalized follow-up question
For Family trip: "Traveling with family, huh? How did the kids enjoy the trip? Any memorable family activities?"
For Friends group: "How was your trip with your friends? Enjoyed the Singaporean hospitality? On a scale of 1-10 ; how would you rate your experience ?"
For Single Travelers: "Solo adventure! Did you find it easy to meet new people or explore on your own? Any particular highlight from your trip?"
For Business Travelers: "Business trip, got it. How were the work facilities and overall convenience? Any good spots for unwinding after work?"
STEP 3) Collect more detailed feedback for the trip experience.
Sample Questions,
a) "How was your hotel accommodation? Was it Clean, comfy, alongside good amenities?"
b) "How about transportation? Was it Punctual, comfy, and safe?"
c) "How were the food arrangements in terms of variety, service, and taste? Were dietary restrictions taken care of"
d) "Did you enjoy the activities and attractions? How would you rate the trip ?"
STEP 4) Aplogize for any poor experience and check if you can compensate the same with discount coupons for the next trip.
Apologize for the bad experience and try to understand what was the issue in detail with follow-up questions.
Example - I am really sorry to hear about your bad experience. We will make sure to work on this with our partners to upheld the high standards of travel experience.
Try to compensate appropriately for poor experience,
Example,
- If the user faced issues related to food - offer a one-time 10% discount coupon on meal for the next trip.
- If the user complains about issues related to accommodation - offer a one-time 15% discount coupon on 4-star hotel accommodation.
STEP 5) Try to find upselling opportunities with lucrative limited time deals.
Once the overall user sentiment is positive after sharing feedback - try to ask a few questions and then try to sell relevant packages.
Example questions - "Thanks for sharing detailed feedback. Before we drop off - a few quick questions about your preferences. What activities do you like? Adventure, culture exploration, relaxation, shopping etc?"
"How often do you travel, like monthly, quarterly, or annually?"
"Any future destinations in mind?"
"Do you prefer traveling alone, with family, or friends?"
"Any special needs like dietary restrictions or accessibility?"
STEP 6) Get the CSAT score
Example: "Almost done! A few more quick ones."
"Would you refer us to friends or family?"
"Do you share your trips on social media?"
"Willing to leave a review on TripAdvisor or Google for Yellow Travels?"
STEP 7 ) Closing Statement
Example: "Thanks a lot, [Traveler's Name]! We appreciate your feedback. Looking forward to your next trip!"
Rules for Having a Conversation Over Voice Channel:
- This conversation is over a voice bot, so use filler words if necessary.
- Keep responses short; your response should not exceed more than 300 characters.
- Since the conversation is happening over a voice channel, the user might interrupt the bot. You can identify the interrupt tag alongside the user's response.
- If you determine the user's response is an interruption, you can take one of the following actions:
(a) Acknowledge the user's interruption with some filler words like "Got it, understood, I see" and then transition smoothly to the next response: "Got it. Understood. Now, as I was saying..."
(b) Restate or summarize what the user mentioned for clarity, but only for complex or long user queries.
(c) Be empathetic to the user's query or interruption.
- If the user's message is "#not-speaking," it means the user hasn't responded. Please confirm with the user by asking "Are you still around?" or "Are you there?"
```
Customer IT Support (store variables)
```
You are a female customer IT support voice AI agent named Sally and you work for a company called Yellow IT. Your goal is to help users with IT issues related to their keyboard or mouse over a voice call.
Steps to help the user debug the issue:
STEP 1: Greetings and Get the user's name (mandatory step)
Collect the user's name. If the user asks for a reason for sharing their name, mention that this is a required step for internal logging.
Example: "Hello, I am Sally from Yellow IT support. I can help you resolve your issues related to IT equipment like keyboard and mouse. Can you please share your name to get started?"
STEP 2: Get the user's mobile number (mandatory step)
Collect the user's mobile number. As part of mobile number validation, a valid mobile number is ONLY of 10 digits. Do not mention internal validation rules to the user. If the user asks for a reason for sharing their mobile number, mention that this is a required step for internal logging. Also, since sharing a phone number from the user's end takes some time; please add #[silence:1] at the end of the response. In case the user shares an invalid mobile number (which is not 10 digits) ; request the user to share the 10-digit mobile number again.
Example bot response in case user shares an invalid mobile number: "Hey it seems like the shared mobile number is incorrect. Can you please share your 10-digit mobile number again?"
STEP 3: Identify if the issue is with Mouse or Keyboard
Once you get the information from the user, ask which product they need help with keyboard or mouse.
If the issue is with the mouse, go to STEP 4.
STEP 4: Check the type of mouse
Check if the mouse the user is using is wired or wireless.
If the issue is with a wireless mouse, go to STEP 5.
STEP 5: Understand the issue the user is facing
Ask, "What kind of issue are you facing with your mouse? Is it related to cosmetic damage, connection issues, buttons not working, batteries, scrolling wheel stuck, or something else?"
If the issue is related to connection issues (connecting to the PC), go to STEP 6.
STEP 6: Check if the user is connecting the mouse for the first time
Ask, "Is this the first time you are connecting the mouse?"
If this isn't the first time the user is connecting the mouse, go to STEP 7.
STEP 7: Recheck the connection to the port
Ask, "Can you try switching the port on the computer where the mouse receiver is connected? Sometimes, there might be an issue with the port of the device as well."
If this still doesn't help, go to STEP 8.
STEP 8: Check the power status of the mouse
Ask, "Is the red power light on the bottom of the mouse turned on or off? If it's not turned on, please check the power switch and turn on the mouse."
If the power status is perfectly fine, go to STEP 9.
STEP 9: Check the type of battery source
Ask, "Is it a rechargeable mouse or does it come with user-replaceable batteries?"
STEP 10: Suggest charging the mouse
For a rechargeable mouse, suggest, "Make sure it is charged for 2 hours once every month." For user-replaceable batteries, suggest, "Make sure they are replaced every 6 months."
If even after replacing the batteries or charging the mouse the issue persists, go to STEP 11.
STEP 11: Check if the mouse works with an alternate laptop or computer
Ask, "Can you try the complete mouse setup with an alternate laptop or computer? If it works with the alternate computer setup, then the issue may be related to the mouse driver file on the personal computer."
If it works with the alternate laptop or computer, go to STEP 12. If not, go to STEP 13.
STEP 12: Share the link to the new driver file for the mouse via SMS
Mention, "I will send you a link to the updated driver file via SMS. Please download and install the latest driver, and then the mouse should start working again. The link can only be sent via SMS and not on any other channel. Alternatively, you can visit the Yellow IT website and download the appropriate driver file from there as well."
STEP 13: Issue needs to be checked with a human agent
Let the user know, "This issue will require assistance from a human agent. Is it fine to transfer the call to an agent?" Once the user agrees to transfer the call to an agent, ask them for the model name of the mouse and how old it is so the agent can better assist.
Rules for having a conversation over the voice channel:
- This conversation is over a voice bot, so use filler words if necessary.
- Answer briefly. Your response should not exceed 300 characters.
- Since the conversation is over a voice channel, the user might interrupt the bot. You can identify the interrupt tag alongside the user's response.
- If you determine the user's response is an interruption, you can take one of the following actions:
(a) Acknowledge the user's interruption with some filler words like "Got it," "Understood," "I see," and then transition smoothly with the next response: "Got it. Understood. Now, as I was saying..."
(b) Restate or summarize what the user mentioned just for clarity. Do this only for complex or long user queries.
(c) Be empathetic to the user's query over the interruption.
- If the user's message is "#not-speaking," it means the user hasn't responded. Please confirm with the user by asking, "Are you still there?" or "Are you there?"
- When you think the conversation is over, add `[hangup]` the end of the reply
- When user sends "#callhangup" only then you need to summarise user interaction and add `#[summary:{
"isUserSatisfied":""
}]` to the reply. Summary value is in string format, if user hasn't responded to any format then set value as "NA"
```
:::info
You can Copy-Paste this code directly into the Dynamic chat node.
:::
---
## Nexus AI Layer
The **Nexus AI Layer** lets you build and run your bot by asking, not clicking. Instead of hunting through dashboards to find the right setting, you describe what you want in plain language and the AI layer does the work - creating agents, writing prompts, indexing knowledge, generating tests, pulling analytics, and more.
It lives in a panel on the right side of the screen, beside whatever you're working on, and it always acts on the bot you have open. You don't need special syntax - just say what you want.
New here? Ask the AI layer to scaffold a whole bot from a one-line description, so you start from something working instead of a blank canvas.
## What you can ask it to do
Here's the kind of thing the AI layer handles, with examples you can paste straight into the panel.
### Build and configure your bot
Stand up and edit the moving parts - agents, Configuration, flows, integrations, functions, and tables.
- "Create an agent for order tracking and give it a tool to look up an order by ID."
- "Tighten the persona in Configuration so the bot stays formal and never promises refunds."
- "Add a flow that collects a name and email, then books a demo slot."
- "Connect our shipping provider's API and map the tracking number into the reply."
- "Add a `loyalty_points` table with columns for user ID and balance."
### Manage knowledge
Build and tune the knowledge base your bot answers from.
- "Index our help center at help.example.com."
- "Add an FAQ for our 30-day refund window."
- "Why isn't the bot finding our shipping policy article?"
### Test and debug
Check coverage, generate and run test cases, and find out why something failed.
- "How well is my order-tracking agent covered by tests?"
- "Generate test cases for the refund flow, including a few tricky edge cases."
- "Run the regression set and tell me what failed."
- "Why did this test case fail, and what should I change?"
The AI layer drafts the tests, runs them, reads the failures, and suggests the fix - so you go straight from "something's off" to "here's what to change."
### Get analytics and insights
Pull metrics, segment users, analyze conversations, and build reports.
- "What's my containment rate this week versus last week?"
- "Break down active users by channel and region."
- "Summarize the most common reasons users dropped out of the booking flow."
- "Build a dashboard for daily resolved conversations."
### Handle inbox and operations
See and act on the support side - conversations, tickets, and agent performance.
- "How many tickets are open and unassigned right now?"
- "Summarize the longest-waiting conversations in the inbox."
- "How is agent response time trending this month?"
### Work with media
Generate and read images, run OCR, and draft messaging templates.
- "Generate a banner image for our summer sale."
- "Extract the text from this uploaded receipt."
- "Draft a WhatsApp template for an order-shipped notification."
## Good to know
- **It works on the bot you have open.** Open a different bot and the AI layer works on that one.
- **It confirms before it changes anything.** When it's about to create, update, or delete something, it shows you the change and waits for your approval first - nothing happens behind your back.
- **You can combine requests.** Ask for something that spans a few areas - "find the step with the most drop-offs and add a fallback there" - and it handles the whole thing in one go.
## Getting the best results
- **Be specific.** "Add a rule so the billing agent never shares another customer's data" beats "make the bot safer."
- **Name the target.** Say which agent, tool, or table you mean when there's more than one.
- **One goal at a time.** For a big change, walk it through step by step and review each result.
## Nexus Tips throughout the docs
Across these docs you'll see **Nexus Tip** callouts like the ones on this page. Each shows how to do the task on that page with the AI layer instead of by hand - they're optional shortcuts. When you spot one, copy the suggested prompt into the panel or adapt it to your wording.
---
## Help Center
## Overview
Yellow.ai’s AI Help Center is a plug-and-play widget that integrates seamlessly into customer websites, serving as an all-in-one support portal. It enables users to interact with an AI-powered agent, raise tickets, access KnowledgeBase articles, and connect with live agents. AI-Copilot consolidates several key functionalities from Yellow.ai’s Inbox, KnowledgeBase, and ticketing system into a single, unified interface.
**Key Benefits:**
* **Centralized ticket management**: AI Help Center allows users to view and manage all tickets they have created in one place. This eliminates the challenge of tracking multiple email tickets, which often get lost across various threads. With AI-Copilot, users can continue conversations on each specific ticket without confusion, improving clarity and streamlining support requests.
* **Unified experience**: Customers can seamlessly switch between interacting with an AI agent, browsing the KnowledgeBase, and communicating with live agents, all within one easy-to-use interface.ontinue conversations related to each specific issue.
> For support: Contact support@yellow.ai.
### Demo Experience
To explore the AI-Copilot features in action, please refer to the demo video below.
> **Try it yourself!**: https://help.yellow.ai
-----
## Components of AI-Copilot
When the AI-Copilot widget is integrated into a website, it contains several important components designed to enhance the user experience:
### AI Agent interaction
Users can continue their interactions with an AI agent, receiving responses from pre-configured flows and KnowledgeBase articles.
### Suggested queries
A list of suggested queries (4) is available to help guide users through their support journey.
### KnowledgeBase access
Users can ask questions, and the AI agent fetches relevant summarized answers with supported links from the KnowledgeBase.
### Documentation access
Users can easily view Yellow.ai’s documentation by clicking the **Go to Documentation** button.
### Live chat integration
If the AI agent cannot resolve the issue, users can connect to a live agent through the built-in chat functionality. If the issue can't be resolved immediately, the agent can create a support ticket.
- You must provide your details such as Name, Contact number and Email ID to verify OTP before connecting you to a live agent.
### Account access
Sign in to your Copilot account using your **Yellow.ai credentials**. This allows you to access and manage your tickets.
### Email ticket management
After signing into co-pilot with their yellow.ai credentials, end users can view and manage their email tickets.
- All email tickets created by users or Agents are available in the Copilot interface.
- Users can view details (such as all the messages from that thread, ticket ID, Priority and created date) and ticket statuses in one location.
### Ticket escalation
If a user needs additional support, they can escalate their existing ticket to the customer support team directly from the ticket details page.
-----
## Configure of AI-Copilot
Configuring the AI-Copilot is similar to setting up a normal AI agent on Yellow.ai. Ticket Escalation cab be additionally configured.
### Configure ticket escalation
AI-Copilot includes the ability for users to escalate tickets to customer support teams. The escalation option is available on the ticket details page.
**Escalation Flow:**
When a user escalates a ticket, an event (`copilot-ui-escalate-ticket`) is triggered with the following data:
* **ticketId**: The ID of the ticket being escalated.
* **userId**: The CDP user ID of the individual escalating the ticket.
**Support Team Actions:**
The support team must configure their bot to handle this escalation event. For example, they may:
* Create an escalation flow that is triggered when the `copilot-ui-escalate-ticket` event is received.
* Inside this flow, they can add logic to alert the assigned support agent or initiate further investigation.
-------
## Copilot deployment
AI-Copilot is deployed on customer websites through the following steps:
1. **Add Stylesheet to the HTML `` tag**: Place the following line at the end of the `` tag in your HTML file:
```html
```
2. **Add configuration script:** Create the `window.__yc__` configuration script and place it at the bottom of the `` tag:
```
```
3. **Add Copilot JavaScript to your website:** After the above script, add the following JavaScript tag just below the closing `` tag:
`script src="https://cdn.yellowmessenger.com/plugin/copilot/latest/dist/index.js">`
Once this code is added to your website, the Copilot widget will be deployed and ready for use.
**Example deployment code**:
```
Yellow Help Center
```
### Existing customizations
Once the deployment code has been added to the webpage (as mentioned earlier), the following elements can be customized:
* **AI-Agent configuration**: The same configuration used for Yellow.ai web widgets applies here, including language settings and other preferences.
* **Logo customization**: You can add a custom logo to the Copilot interface by modifying the `window.__yc__.logo` configuration in the script.
* **Translation**: Users can enable translation to switch the language of the AI-Agents messages, but the entire website will remain in English.
### Upcoming features and customizations
Currently, some customization options are controlled from the **backend**, but they will soon be made available for user configuration. These features include:
* **Suggested queries**: Customize the four default queries displayed to users.
* **Callout messages**: Ability to modify the “We are here to help you” message.
* **Documentation link**: Modify or add documentation links in the "Go to Documentation" button.
* **Website language**: Switch the language of the entire website, including the AI-agents’s messages and other fields.
* **Account access**: Currently, access is limited to Yellow.ai credentials. However, authentication can also be configured on the client’s end.
---
## Introduction to Analytics
## Analytics overview
**Analytics** is an AI-powered module designed to help businesses monitor and interpret every conversation that happens within their Yellow.ai platform. Whether the conversation is between a user and an **AI agent**, or between a user and a **human agent**, Analyze brings clarity, structure, and actionable insights to each interaction.
It solves a fundamental challenge: **understanding and scaling customer interactions at volume**. With thousands of conversations occurring every day, manually reviewing each one is time-consuming and impractical. Analyze simplifies this by organizing data, highlighting problem areas, and recommending next steps—turning complex conversation data into business intelligence.
> **Flagship Feature: Topics**
> The **Topics** sub-module is the centerpiece of Analyze. This **gated feature** uses Yellow.ai’s in-house LLM to automatically categorize conversations, detect user sentiment, generate article suggestions, and identify automation opportunities. It helps businesses uncover what customers are talking about—at scale.
**Why use analytics?**
- Quickly understand what users are asking about
- Measure how well the AI agent is resolving queries
- Assess user sentiment to improve customer satisfaction
- Identify high-impact areas to increase automation and reduce manual support
- Learn from both AI agent and human agent responses to improve long-term resolution quality
---
## Access Analytics
To access the Analyze module, you must have **any one** of the following permissions:
- Super admin
- Admin
- Insights admin
- Developer
> Refer to [manage your bot users](https://docs.yellow.ai/docs/platform_concepts/get_started/add-bot-collaborators#share-bot-access) article to understand how to request or provide access to use the Analyze module in a bot.
---
## Analytics in-depth
Analytics consists of four powerful sub-modules:
### 1. Topics
The **Topics** module automatically categorizes conversations into subject-based groups using LLMs. For instance, conversations about a refund policy would be grouped under the topic **Refund Policy**.
Within each topic you can see:
- An AI-generated Topic Description provides a concise summary of what users are asking. Topic Clustering helps identify and group related conversations, enabling better analysis, debugging, and AI training.
- User Sentiment insights reveal whether interactions were positive, neutral, or negative, while the Containment Rate shows how effectively the AI agent resolved queries without human handover.
- Article Suggestions recommend relevant knowledge base content based on past interactions, helping improve automation and reduce ticket volume.
- Conversation Share indicates the number of sessions linked to each topic, and CR Opportunities highlight instances where human intervention was needed, pointing to areas where automation can be enhanced.
By clicking a topic, you can dive into detailed analytics, view associated sessions, and understand both what’s working and what needs improvement.
:::note
Topics is a **gated feature** and uses AI-generated insights to power much of its functionality.
:::
:::note
Conversations with fewer than three messages are not analyzed, as there isn't enough context to form a meaningful interaction.
:::
---
### 2. Conversation logs
The **Conversation logs** section gives you access to all conversations happening across all the channels— whether handled by the AI agent or escalated to a human agent. Each individual interaction is stored as a **session**. The same user might have multiple sessions, and each session can be explored in detail.
You with access can:
- Review every message exchanged in a session
- Filter sessions by ID, tags, or specific criteria
- View user details and metadata
This module is useful for digging into specific conversations. However, when the volume of sessions becomes large, Topics can provide deeper and simplified insights.
---
### 3. Message view
**Message view** helps assess how well the AI agent understands and responds to individual user messages. It offers:
- Accuracy analysis of AI responses
- Insights into how well the AI agent handles unseen or unexpected inputs
- Feedback loop to improve AI agent training
This view is essential for teams that want to fine-tune the conversational quality.
---
### 4. Chat metrics
**Chat metrics** provides granular insights into how user interactions unfold at each step of the conversation. This section tracks how every **dynamic chat** node performs - completion rate, token consumption and failures.
By analyzing these node-level interactions, you can:
* Understand where users drop off or need support
* Pinpoint areas where the conversation flow needs improvement
You can fine-tune your conversational design and measure performance beyond just session-level data.
-----
## How Analytics works for Voice ai-agents?
Conversations with Voice AI agents are stored in two ways:
- **SAML Tag Links**: Clicking the tag redirects you to the corresponding voice recording, which you can listen to directly.
- **Text Transcripts**: Conversations may also be transcribed and displayed as readable text.
Regardless of how the conversation is stored in the UI (as audio or text), all interactions are transcribed, analyzed and displayed within **Analytics**.
---
## Analytics for Dynamic chat node
**Analyze chat metrics** provides insights into bot performance, focusing on Dynamic chat nodes. Key metrics include total user sessions, node completion rates, inputs captured, node failures, and token consumption. These metrics help assess user engagement, track failures, and help to optimize bot interactions to meet business goals.
> These metrics can be filtered for a particular time-range by clicking the data dropdown on the top right.
The Chat Metrics tab offers the following widgets which can be used for the user decisions / business goals/ billing purpose:
1. **Total user sessions**: This widget shows the overall count of sessions that took place between users and the bot during the chosen time frame, specifically when utilizing dynamic chat nodes.
2. **Node user stats**: Node user stats offer insights into user interactions with the Dynamic chat node. For instance, if 100 people initially engaged with the chat node, and 40 discontinued their participation during the conversation, the remaining 60 users either exited the flow upon request, submitted all required information, or successfully reached the goal set in the dynamic chat node, resulting in a 60% completion rate.
* **Users entered**: This represents the count of unique users who entered the dynamic chat node (same user can enter the flow more than once increasing the count).
* **Users dropped**: This indicates the number of users who abandoned the conversation or remained unresponsive for over 24 hours.
* **Users completed**: This shows the number of users who either supplied all mandatory inputs, attained the business objective specified in the dynamic chat node, or were allowed to exit the node as per their request.
* **Completion rate**: This metric signifies the completion rate of the Dynamic chat node, calculated as (Users Completed / Users Entered) * 100.
> Click **View Chat** link next to the relevant node name, to access conversation logs filtered by the chosen time frame, flow name, and node name within that flow.
3. **Inputs Captured**: This widget tracks the number of users who have supplied specific information, such as their name and phone number, to the bot while utilizing the dynamic chat node. You can narrow down the data for each node by selecting the node name from the dropdown menu located at the bottom.
- **Input**: Displays the user's utterance provided to the bot.
- **Count**: Shows how many times a specific utterance has been used on the bot.
4. **Node failures**: This widget highlights the reasons behind bot failures during specific interactions. You can refine the data for each node by choosing the node name from the dropdown menu at the bottom.
> Click the **View Chat** link next to the relevant reason, to view conversation logs filtered by the chosen time frame for a specific node within the flow and categorized under the node failure reason.
5. **Token consumption**: This widget tracks the utilization of tokens in dynamic chat node usage, providing information on various aspects:
* **Model**: Indicates the specific LLM model employed, such as GPT-3.5 Turbo, etc.
* **Credentials**: Refers to the source of credentials, which can either be from a third-party provider or from yellow.ai.
* **Provider**: Identifies the service provider, which could be Azure, Open AI, Anthropic, Yellow G, etc.
* **Prompt tokens**: Represents the input tokens furnished to the model.
* **Response (completion) tokens**: Denotes the output tokens generated by the model.
:::info
**Tokens explained:**
**Tokens** can be understood as fragments of words. Prior to processing prompts through the API, the input is divided into tokens. It's worth noting that tokens don't always align exactly with the beginnings or endings of words; they can encompass trailing spaces and even sub-words. To provide a sense of token lengths, here are some helpful guidelines:
* 1 token approximately equals 4 characters in English.
* 1 token is roughly equivalent to 3/4 words.
* About 100 tokens correspond to approximately 75 words.
* Alternatively, 1-2 sentences are encompassed in approximately 30 tokens, while a single paragraph is around 100 tokens.
* Approximately 1,500 words are represented by roughly 2048 tokens.
If you wish to explore how various providers calculate token quantities, you can refer to the following resources:
* [Open AI token](https://platform.openai.com/tokenizer)
* [Azure Open AI token](https://azure.microsoft.com/en-in/pricing/calculator/?service=openai-service)
* [Anthropic token](https://www.anthropic.com/pricing#api)
:::
---
## Analytics overview
The **Overview** page provides a high-level snapshot of agent performance, user engagement, and conversation trends. It helps you quickly understand how your AI agent and human agents are performing, what users are talking about, and where improvements can be made.
The **Overview page** is your single dashboard for:
* Tracking adoption and usage growth.
* Monitoring automation efficiency (containment, AI agent involvement).
* Identifying key conversation topics and sentiment shifts.
* Understanding user demographics and behavior.
To access the Analytics overview page, go **Analytics > Overview**
### **Filters in Overview**
The Overview dashboard includes filters that let you customize the data view. These filters make it easier to drill-down into relevant timeframes and channels for precise performance evaluation.
* **Time range**
* **Last 7 days** – View short-term performance and recent trends.
* **Last 30 days** – Track medium-term patterns and stability.
* **Custom** – Select any specific date range for deeper analysis.
* **Channels**
* **All channels (default)** – Combined data across all support channels.
* **Voice** – Filter to only see insights from voice interactions.
* **Web chat** – Focus exclusively on chat-based conversations.
---
### Agent Performance
This section highlights metrics derived from conversations analyzed by AI.
* **Total conversations** – Total conversations handled by your AI agent and human agents.
* **Analyzed conversations** – Subset of conversations reviewed by AI for insights.
---
### Resolution Rate
Resolution rate represents the percentage of conversations that were successfully resolved across all topics within a conversation. A conversation is considered resolved when the user’s query is fully addressed without requiring further escalation.
**What it shows**
* A timeline view of resolved conversations, helping you analyze resolution trends over time.
* A comparison of resolution performance between AI Agents and Human Agents, so you can see how much each contributes to overall query resolution.
> Resolution Rate = Resolved conversations ÷ Total analyzed conversations
> A conversation is considered resolved when the user does not express dissatisfaction for any topic within it. Conversations where only some topics are resolved are not included in this metric.
---
### Resolution Rate Split
Resolution rate split provides a breakdown of analyzed conversations by their resolution outcome. Instead of just showing the overall resolution percentage, it categorizes conversations into distinct resolution states.
**Resolution states**
* **Resolved** – The conversation was successfully completed, and the user’s query was addressed.
* **Unresolved** – The query could not be resolved.
* **User drop-off** – The user exited the conversation before it was completed.
* **Partially resolved** – Some parts of the user’s request were addressed, but not fully resolved.
**What it shows**
* A distribution view of all analyzed conversations, grouped by outcome.
* Helps you identify where conversations are getting completed, abandoned, or left partially handled.
**Available filters**
* **All (default)** – Shows outcomes across both AI and Human agents.
* **AI Agent** – Focuses on outcomes where the AI Agent handled the conversation.
* **Human Agent** – Focuses on outcomes where a live agent handled the conversation.
---
### Top discussed topics
Displays the most frequently occurring categories in analyzed conversations, along with their occurrence count (Topic – Count). This gives you a clear view of what users engage with the most.
Click the link on this card to navigate to Conversations > Topics for the full list of topics and detailed counts.
---
### Containment Rate
Containment rate measures the percentage of conversations that were fully handled by the AI Agent without requiring a handoff to a human agent.
**What it shows**
* Tracks how effectively the AI Agent can manage end-to-end conversations.
* Provides a time-based view of containment, helping you monitor improvements or declines over specific periods.
> A higher containment rate indicates stronger automation, reduced dependency on human agents, and improved cost efficiency.
> A lower containment rate may suggest gaps in the AI Agent’s training, prompts, or workflows that need optimization.
---
### User Sentiment
User sentiment analysis measures how customers feel during conversations, based on AI-driven sentiment detection. Each conversation is categorized as **Happy**, **Neutral**, or **Unhappy**.
**What it shows**
* Displays sentiment trends over time, helping you track how customer experience evolves.
* Shows the share of each sentiment category as percentages for the selected period.
---
### Usage Trends
Usage Trends highlight overall engagement levels on your platform. The metrics reflect activity across all conversations within the selected time frame.
**What it shows**
* **Users** – Unique users interacting with the agent.
* **Messages** – Total number of exchanged messages.
* **Conversations** – Number of conversations started.
* **Average session duration** – Typical duration of a user’s session.
---
### User Split
Breakdown of users across different dimensions displayed in pie chart for easy comparison. By default, it shows the report by channels. The following are the different filters available:
* **Channel** – Voice, Web chat, WhatsApp
* **Device** – Desktop vs. mobile.
* **Country** – Geographic distribution of users.
---
### AI Agent Involvement
This metric shows how much of the overall support workload is being managed by AI Agents. It reflects the distribution of conversations between automation (AI Agents) and human agents.
**What it shows**
* Breaks down conversations handled partially or fully by AI Agents versus those requiring human intervention.
* Highlights how often AI Agents are engaged within conversations, giving visibility into their contribution across support operations.
---
## AI Knowledgebase Suggestions
:::info
AI Knowledgebase Suggestions are generated for the top 15 topics.
:::
## Overview
Customer support teams often handle repetitive queries like password resets and payment updates, leading to delays and inefficiencies. Yellow.ai’s AI-powered Knowledgebase Suggestions streamline this process by analyzing interactions and generating relevant knowledgebase articles, improving efficiency and customer satisfaction.
### Challenges & solution
Handling repeated queries slows response times, consumes valuable agent time, and makes it difficult to access accurate information. Yellow.ai solves these issues by automating knowledgebase creation through AI-powered analysis of human and AI interactions. The system identifies frequent topics and generates relevant articles, ensuring faster resolutions and reducing agent workload.
#### Key features
* **Smart article suggestions**: Detects common topics and suggests relevant content.
* **AI-Powered article creation**: Generates clear, searchable articles.
* **Customizable content management**: Allows easy editing and alignment with policies.
* **Article publishing & management**: Stores finalized articles for AI and human agent use.
------------------
## Article suggestion features
AI knowledgebase suggestions are displayed for topics that have the **Article Suggestion** icon enabled.
Clicking on the **Article Suggestion** icon reveals the following options and features:
### 1. AI-Generated article for the selected topic
The AI-generated article is tailored to the selected topic. The topic name is prominently displayed at the top, ensuring clarity and easy identification of the article you are working on.
### 2. AI suggestions
The AI system provides updates or improvements based on past conversations. These suggestions vary depending on the type of resolutions previously provided.
- **Add suggestions**:
- Click the **Add** button to incorporate AI suggestions into the Knowledgebase article.
- The added suggestions will appear on the left-hand side of the interface.
- **Not relevant suggestions**:
- If a suggested article is not relevant, click **Not Relevant** to remove it.
- The irrelevant suggestion will be deleted from the list.
### 3. Edit section
Each section of the AI-generated content can be customized to fit your specific requirements.
- Add new information.
- Remove irrelevant details.
- Modify existing content to improve accuracy and clarity.
### 4. Archive sections
AI provides multiple suggestions for articles based on diverse conversations and resolution types.
- After reviewing and adding these suggestions to your Knowledgebase, you can archive sections that are no longer needed.
### 5. Archive tab
The **Archive Tab** contains all the article sections you have previously archived.
- **Add archived sections**: Click **Add** to reinstate an archived section back into your Knowledgebase.
- **Delete archived sections**: Click the **Delete** icon to permanently remove an archived section.
### 6. Save changes
Once you have reviewed and made edits to the AI-generated articles, click **Save Changes** to store your updates.
- This is a **universal save button** that ensures all changes on the Article Suggestion page are saved immediately. Saved articles will be available in your [Knowledgebase](https://docs.yellow.ai/docs/platform_concepts/inbox/knowledge-base/kboverview).
:::note
Articles saved in the Knowledgebase will not appear on your website. However, they remain accessible within the Yellow.ai platform for future reference and AI agents knowledge.
:::
---
## Call logs
This page provides detailed insights into every call handled through the platform. It includes information such as call direction, participants, duration, and resolution status.
This report helps administrators, supervisors, and analysts monitor call activity, troubleshoot issues, and evaluate performance.
:::note
The log data refreshes automatically every 30 minutes.
:::
---
## Accessing the Report
1. In the left navigation, go to **Analytics > Conversations > Call Logs**.
2. Apply the required filters.
3. View or export the report.
---
## Report Columns
| Column Name | Description | Example |
| ----------------- | ----------------------------------------- | ---------------------- |
| **Call ID** | Unique identifier for the call. | `c123456` |
| **Recording** | Link to call recording (if available). | `Play` |
| **Direction** | Direction of the call (Inbound/Outbound). | `Inbound` |
| **From** | Caller’s number or ID. | `+1-202-555-0147` |
| **To** | Receiver’s number or ID. | `+1-202-555-0173` |
| **Duration** | Total call duration. | `5m 32s` |
| **Start time** | Timestamp when the call started. | `2025-09-12 14:03:12` |
| **Status** | Final call status. | `Completed` / `Missed` |
| **Hangup reason** | Reason for call termination. | `User ended` |
---
## Drill-down call logs data
Filters
You can refine the report using the following filters:
| Filter Name | Description | Example |
| --------------------------- | --------------------------------------- | --------------------- |
| **Status** | Filter by call outcome. | `Completed`, `Missed` |
| **From** | Search by caller ID or number. | `+91-98765-43210` |
| **To** | Search by receiver ID or number. | `+91-98765-67890` |
| **Direction** | Choose call type. | `Inbound`, `Outbound` |
| **Hangup reason** | Filter based on why the call ended. | `Network error` |
| **Ringing duration** | Time spent ringing before pickup. | `12s` |
| **Call duration** | Total length of the call. | `5m 32s` |
| **Voice bot duration** | Duration handled by a voice bot. | `2m 15s` |
| **Voice bot bill duration** | Billable bot interaction time. | `2m 15s` |
| **Campaign ID** | Identify calls linked to a campaign. | `cmp-2025-08` |
| **Hangup source** | Source that triggered call termination. | `System` / `Agent` |
---
## Available Actions
#### **Download/export** in CSV, XLSX, or PDF format
#### Search data by call ID
#### **Access call details**
To view the details of a specific call:
1. Search or filter to locate the required call record.
2. In the Call logs table, click the Call ID link.
3. The detailed call view opens, showing transcript, recording, metadata, and logs (if available).
Perfect — thanks for the details. Here’s a **clean, structured draft** for the **Call detail view** section, written in the style of Google/Microsoft/SAP docs:
---
### Call detail view
When you select a call from the **Call logs** table, the system opens the **Call detail view**. This view is organized into tabs, allowing you to review different aspects of the call.
#### 1. Conversation Details
* **Conversation transcript** – Full transcript of the call.
* **Recording playback** – Option to listen to the audio recording.
* **Copy chat URL** – Share the conversation link directly.
#### 2. Metadata
Displays all key attributes of the call, including:
* **From** – Caller number
* **To** – Recipient number
* **Call ID** – Unique identifier for the call
* **Start time** – Timestamp of when the call began
* **End time** – Timestamp of when the call ended
* **Call duration** – Total length of the call
* **Ringing duration** – Time before the call was answered
* **Hangup reason** – Why the call ended (for example, *Normal Hangup*)
#### 3. Debug logs
Shows system-level logs generated during the call for troubleshooting and analysis.
#### 4. Comments
Add notes, tag team members, and collaborate on call-specific observations directly within the platform.
#### Refresh Call Log
By default, the system refreshes log data every 30 minutes. However, you can refresh Call logs data manually whenever needed using the **Sync data** option.
---
---
## Conversation logs
Conversation logs contain detailed records of every interaction between users and the AI-agent in chronological order. These logs include user inputs, AI-agent responses, timestamps, and any contextual data relevant to the interaction. They provide a complete history of conversations, helping AI-agent developers to understand how the AI-agent is performing, identify issues, and make improvements to enhance the user experience.
Chats are retained for six months; after this period, they are archived. You can still download them using [Data export](https://docs.yellow.ai/docs/platform_concepts/growth/dataops).
---------------
## Features available
Conversation logs provide a comprehensive set of tools for managing and analyzing conversations. Below is a detailed list of all the available features:
| Feature | Description |
|---------|-------------|
| **Filters & Search** | Filter conversations based on criteria such as date, source, labels, tags, nodes, and session ID (SID). Search for conversations using UID (User ID) or SID (Session ID) to pinpoint specific interactions. |
| **Logs** | View detailed logs for each message, including timestamps, actions taken by the AI-agent, and flow execution. View knowledge base search results related to the conversation, helping troubleshoot issues with document nodes. Inspect the flow and nodes triggered during the conversation to troubleshoot and improve AI-agent performance. |
| **Comments** | Add, reply to, and resolve comments on specific messages to communicate with team members about certain issues. |
| **Flag** | Flag conversations to revisit later for follow-up, review, or escalation, helping prioritize important interactions. |
| **Copy URL** | Share the conversation log URL with team members for easy access to specific interactions. |
| **User Details** | View important details about the user, including their UID, session information, and labels applied. |
| | **Labels**: Manually added by users to categorize conversations (e.g., for tracking complaints, feedback, etc.). |
| |**Tags**: System-generated tags automatically assigned to conversations based on detected issues. |
---------------
## User session
A **user session** refers to a continuous interaction between a user and the AI-agent within a specific time window. A session starts when the user initiates a conversation with the AI-agent and ends when:
- [**Chat channels**](https://docs.yellow.ai/docs/platform_concepts/channelConfiguration/overview) (e.g., chat widget, WhatsApp, web apps): Sessions last for **24 hours** from the user's **first message** in that conversation window.
- **Email channel**: There is **no fixed session duration** for email interactions. Since users may respond after several hours or even days, emails are handled as individual communications rather than a single continuous session.
- **Voice calls**: The session ends **as soon as the call is disconnected**.
Each user is identified by a **unique ID (UID)**, and a conversation log is generated for each UID. This log captures the full context of all interactions during the session. Each session has a **session ID (SID)**.
> You can search for a particular conversation using **UID** or **SID** (Session ID) to locate specific sessions easily.
> **To get session ID of an Ongoing Conversation**, use `{{{session.id}}}`. This placeholder returns the unique identifier for the active conversation session.
**Session expiry explained**
- A session lasts for **24 hours** from the user's last message.
- If the user sends another message **within 24 hours**, the **same session continues**.
- If the user sends a message **after 24 hours**, a **new session starts**.
**Example scenarios**
| Scenario | Timeline | User Action | Result |
|:-------------------|:---------|:------------|:-------|
| **Continued Session** | 9:00 AM - Start9:30 AM - Last message6:00 PM - Next message (same day) | User sends a message **within 24 hours** | Same session continues.Session expiry shifts to **6:00 PM next day**. |
| **New Session** | 9:00 AM - Start9:30 AM - Last message9:31 AM - Next message (next day) | User sends a message **after 24 hours** | New session starts.Previous chat history is available, but **context is lost**. |
> Q1. How can I get the current session ID of an ongoing conversation?
> A: You can retrieve the session ID using `{{{session.id}}}`. This placeholder returns the unique identifier for the active conversation session.
:::note
When users starts a new session (after 24 hours), they can view the previous conversation history, but the context from the earlier session is not retained.
:::
:::note
By default, the names displayed in conversation logs are randomized to maintain end-user anonymity.
To display actual user names, contact support team.
:::
--------
## Access
To access the conversation logs, navigate to **Analyze** > **Conversation Logs**. You can open the detailed view of the conversation to inspect the interaction history.
### Share
You can share the conversation logs with your team members to review and discuss specific interactions, which helps in identifying problems and finding solutions.
Go to the conversation log and copy the chat URL.
> You can share the URL with the specific user or team members.
### Flag conversations
By flagging a conversation, you can easily mark it for review, follow-up, or escalation. This ensures that critical issues, such as unresolved complaints or urgent inquiries, are promptly addressed. Flagging also helps organize conversations for further analysis and improves the management of user interactions.
To flag a conversation, follow these steps:
1. Go to the desired conversation and click the **Flag** icon on the top right corner.
2. To view your marked conversations, go to **Filters** > **Flagged Conversation** > **Apply filter**.
-----------
## Search and Filter
You can Search and filter conversations to extract relevant and meaningful information from a large volume of chats. Filters help you quickly identify important interactions, better understand user queries, and troubleshoot problems.
To **filter** chat logs, follow these steps:
1. Click **Filters** on the top right corner.
2. Set the filters based on your preferences. For detailed information on each filter criterion, refer to the table below:
| Filter | Description |
|-------------------------|------------|
| **Date** | Filter conversations within a specific date range using the calendar selection. |
| **Source** | Filter by source/channel (e.g., WhatsApp, Skype, Facebook, etc.). Pick the desired source from the dropdown menu. |
| **Tags** | Filter by system-generated tags, such as "Validator Limit Exceeded" or "Fallback Limit Exceeded." |
| **Flag conversation**| Filter conversations that are flagged for follow-up, review, or escalation. |
| **Labels** | Filter conversations based on custom labels applied by users. |
| **Flows** | Filter conversations associated with a particular journey, including step and drop-off specific filters. |
| **Nodes** | Refine conversations based on specific nodes triggered. For example, filter all conversations where a phone number was collected. |
| **SID** | Filter conversations using the unique Session ID.|
3. Click **Apply filter** after setting the criteria.
> A red dot appears next to the field to indicate that a filter is applied.
**Search**
You can use the **search** bar located in the top right corner to easily search for a specific chat by entering the UID (User ID).
-------------
## User details
View basic details, tags, and labels associated with the chat.
> You can download the user's profile by clicking the download icon next to the user's name.
### Tags
The platform automatically assigns tags to conversations to highlight key events, making it easier for developers and analysts to troubleshoot.
To view tags check the **Tags** column to see the status of the tags or open the chat and check the conversations.
> You can view the node information when you open a tag, you can rectify the issue within [Automation (flows/nodes)](https://docs.yellow.ai/docs/platform_concepts/studio/build/Flows/flows-overview).
**Available tags**
- **Validator limit exceeded**: Assigned when the validation limit is exceeded for a user input, indicating that the input was invalid (e.g., incorrect format or length).
- **Missing bot response**: Assigned when the AI-agent fails to generate a response to the user.
- **Unused quick replies**: Assigned when users respond with free text instead of selecting from the available quick replies, signaling potential usability issues.
- **Fallback limit exceeded**: Assigned when the AI-agent triggers fallback multiple times and exceeds the set fallback limit.
- **Unidentified**: Assigned when the AI-agent is unable to comprehend the user’s input, often due to ambiguity or unclear phrasing.
- **Human takeover**: Assigned when the conversation is handed over to a human agent for further assistance.
> You can filter conversations by these tags to monitor and address areas needing improvement.
### Labels
**Labels** are added manually by users to categorize and organize conversations. Labels make it easier to track specific types of interactions, such as complaints, inquiries, feedback, or technical issues. They help manage the flow of conversations and ensure that critical issues are addressed.
To label a chat, open a conversation. Under **User deatils**, add a label to the conversation by typing it.
**To view the chat with the selected label**
Open **Filters** > **Labels** > select the label from the drop-down > **Apply filter**.
:::info
**Labels** are manually added by users to help categorize conversations.
**Tags** are automatically generated by the system to highlight conversation issues.
:::
--------
## Debug conversations (Logs)
To debug and resolve issues in a conversation, you can enable logs for that specific interaction. This helps you gain a clearer understanding of how to address the problem and fix it.
To view logs of each action within the chat, follow these steps:
1. Open the **Logs** tab.
2. Click the **Debugger** icon to view logs for any user input. This helps trace the sequence of actions taken by the AI agent in response, making it easier to troubleshoot issues and improve performance.
3. Associated nodes and logs are displayed for each action. Expand any item to view the specific log or node where the conversation logic was executed.
**View KB report/log**
To view **KB Report logs** open the Logs tab and clicking KB report icon which is available for logs generated when a document search node has been used..
**KB report includes**: Query, Previous user messages, Rephrased query, Answer, Status code, Confidence, Trace ID, Tags and Site key.
**Viewing log for Document search node (Demo):**
---------
## Comments
**Comments** feature within conversation logs improves the user experience by enabling teams to create, manage, and resolve tasks directly within the system. Following are the tasks that can be accomplished with Comments for different teams:
| Customer teams | Delivery/Support teams| Bot developers |
| -------- | -------- | -------- |
| - Add comments to specific messages to effectively communicate issues. - Filter and view open and resolved comments for better tracking. - Reply to comments to collaborate with other teams. |- View all open and resolved comments. - Filter comments by status for prioritization. - Reply to comments and mark them as resolved to manage workflows efficiently. | - Review comments added by customer teams to address specific issues. - Reply to comments to provide updates or clarification. - Mark comments as resolved once issues are handled. |
To use **Comments**, follow these steps:
1. Open a conversation and open the **Comments** tab.
2. You can see a **+** icon next each message within the conversation. Click **+Add comments**, type a comment (200-character limit) and hit send icon.
3. **Reply to comments**: Engage in threaded discussions by replying to specific comments.
4. **Mark comments as resolved**: Change the status of comments to resolved when issues are addressed.
5. **Auto flagged comments**: Chats containing comments (both open and resolved) are automatically flagged for easy filtering.
6. **View and manage comments**: Filter and view open or resolved comments for easier tracking. Resolved comments are visually grayed out for distinction.
:::note
The comment button is displayed only when users are in the **Comments** tab.
:::
---
## Topic Analysis for 3rd-party ticketing tools
:::note
In this article, we refer to any non-Yellow.ai inboxes as 3rd-party apps.
:::
## Understand automation rate for 3rd-party inboxes
**Automation rate** refers to the number of conversations handled solely by the AI agent without any human agent intervention. When a conversation is transferred to a human agent, the automation rate decreases, indicating that the AI agent was unable to fully resolve the user’s query.
There are two types of chat transfers:
1. **Active handover**
* **Yellow.ai Inbox**: The conversation is transferred to a human agent through the agent-transfer event.
* **3rd-Party Inbox**: The AI agent is paused, and the chat is handed over to a human agent using an event configured at the AI-agent level. However, these transfers are not tracked by default.
2. **Passive handover**: In passive handovers, the AI agent collects relevant information and routes the query through alternative methods instead of a live chat:
* **Schedule callback**: The AI agent collects user details and schedules a callback.
* **Email**: The AI agent creates a support ticket via email.
* **Ticket in 3rd-party system / Trigger event**: The AI agent raises a support ticket in an external system or triggers a custom event.
Transfers within the Yellow.ai Inbox are tracked using the `agent-transfer` event. However, when using a 3rd-party inbox, these handovers rely on AI-agent-level configuration and are not trackable out of the box.
### Using the chat handoff node
When working with 3rd-party inboxes, it is important to track sessions where the AI agent was unable to resolve the query and the issue was escalated—similar to how it's done within the Yellow.ai Inbox. This is achieved by logging the `agent-transfer` event.
With **Bot Developer** access, you can configure the **Chat Handoff** node just before the ticket creation node (e.g., for Zendesk, ServiceNow, Intercom, etc.). When this node is triggered, it logs the `agent-transfer` event in the [**User Engagement Events**](https://docs.yellow.ai/docs/cookbooks/insights/eventdescriptions#user-engagement-events) table.
This setup enables visibility into sessions that involved agent intervention—even if managed outside Yellow.ai Inbox—helping teams measure automation rates and identify opportunities for improving the AI agent’s effectiveness.
#### Example: Tracking Agent Sessions via Zendesk
When a ticket is raised in **Zendesk**, the **Chat Handoff** node is triggered just before the handoff. Once the passive or offline ticket is created, agents typically respond via email, call, or other channels. This handoff is recorded as an `agent-transfer` event in the **User engagement events** table, making it measurable.
The **Chat Handoff** node acts as a consistent marker for agent involvement across 3rd-party systems, ensuring automation metrics remain accurate.
**User engagement events table**:
------------
## Analyze transcripts from 3rd-Party Inboxes
When a ticket is created in a 3rd-party inbox, the resulting interactions can span multiple channels such as calls, emails, web chats, and SMS. However, by default, Yellow.ai does **not** have access to transcripts from 3rd-party ticketing tools. This limitation restricts visibility to only the interactions between users and AI agents, excluding conversations handled by human agents via external systems.
To bridge this gap, Yellow.ai enables the import, analysis, and display of transcripts and insights from 3rd-party ticketing tools directly within the **Analyze** module.
**Flow comparision**:
| Yellow.ai workflow | 3rd-Party workflow |
| -------- | -------- |
| - The AI agent handles user queries. - A live agent takes over, pausing the AI agent. - Once the live agent exits, the AI agent resumes. | - The AI agent responds to the user.- The system creates an offline ticket while the AI agent remains active.- The chat continues without a defined session end time. |
**3rd-Party workflow:**
After the handover to the 3rd-party system, Yellow.ai receives the ticket details. Once the ticket is closed (regardless of when), Yellow.ai analyzes the transcript and displays both the conversation and insights in the **Analyze** module.
#### Setup requirement
Yellow.ai's backend does not automatically initiate ticket closure or transcript fetching when it receives offline ticket messages. To enable this process, you must:
1. Create an automation rule in your 3rd-party ticketing system (e.g., Freshdesk, Zendesk).
2. Configure a webhook that sends ticket updates to Yellow.ai.
You can set up this webhook using Yellow.ai’s [**Integration**](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/overview) module.
:::info
Webhook URL for the connected account can be fetched from **Yellow.ai > Integration > Your 3rd-party Inbox > Weebhook URL** beside the account name.
:::
### Configure Freshdesk webhook
#### Set up Freshdesk webhook
Follow these steps to enable automations and set up a webhook:
1. **Log in to your Freshdesk account**: Use your credentials to log in to your Freshdesk account.
2. **Go to admin settings**: Click on Admin in the left-hand sidebar to open the configuration options.
3. **Open the automation section**: In the Workflows section of the admin settings, click on Automations to access workflow and trigger management options.
4. **Select Ticket Updates**: Under the automations tab, choose **Ticket Updates** to create rules for ticket-related updates.
5. **Define webhook trigger conditions**: Specify the conditions for the webhook trigger. Add the required criteria to ensure the webhook activates under the appropriate circumstances.
6. **Action settings**: Add the action settings as below.
#### Enable Freshdesk events on Yellow.ai
1. **Go to automation**: Open Yellow’s platform and navigate to **Automation** from the sidebar.
2. **Access events**: In the automation settings, go to **Events** and select **Integrations**.
3. **Activate the Freshdesk event**: Locate the **freshdesk-ticket-updated** event and activate it for the connected Freshdesk account.
Once configured, you can see the analysis generated on the Analyze module for the chats happening on the 3rd-party apps.
:::info
Learn more about **Freshdesk integration** [here](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/freshdesk).
:::
--------------
### Configure Zendesk webhook
To receive notifications for ticket updates within Zendesk's offline ticketing system, you can set up webhook and trigger.
#### Create a Webhook
To configure a webhook for receiving ticket update notifications, follow these steps:
1. Log in to your Zendesk account.
2. Go to **Admin Center** by clicking the **Admin icon** in the sidebar.
3. Navigate to **Apps** > **Integrations** > **Webhooks**.
4. Click on **Create Webhook**.
5. In **Name** field, enter the name of your webhook.
6. In **Endpoint URL**, provide the URL where you want to receive the notifications.
8. In **Request** method, select POST.
9. In **Request** format, choose JSON.
10. Click **Create** to save the webhook.
#### Create a trigger
To notify the webhook when a ticket is updated, set up a trigger:
1. Go to **Admin center** by clicking the **Admin icon** in the sidebar.
2. Navigate to **Objects and rules** > **Triggers**.
3. Click on **Add trigger**.
4. In trigger details, enter a **Name** of the trigger.
5. In **Conditions**, define when the trigger should activate (example, when a ticket is updated).
6. In **Actions**, set the action to notify the webhook you created.
:::info
Learn more about **Zendesk integration** [here](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/zendesk-offline-ticketing).
:::
---
## Expanded insights into each topic
Click on the **Topic name** to view a detailed analysis of the selected topic.
:::info
All the data related to topics can also be viewed in **Data explorer > [Contained resolution analysis](https://docs.yellow.ai/docs/cookbooks/insights/eventdescriptions#contained-resolution-analysis)**.
:::
## Date filter
By default, analytics for the selected topic are filtered to the past 30 days. You can adjust the time period by selecting a different date range.
## Automation opportunity
Automation opportunity is the potential for automating user queries in this topic. This represents the percentage of conversations that either were not resolved or not contained, calculated as:
> **Automation Opportunity** = (Total unresolved/uncontained conversations in this topic) / (Total unresolved/uncontained conversations across all topics).
## Conversation share
This shows the percentage of total conversations for the selected topic relative to all conversations across topics, calculated as:
> **Conversation share** = (Total conversations in this topic) / (Total conversations across all topics).
You can view all conversations under a specific topic by clicking **View all conversations**. For each conversation, you will find the following details:
- **All Conversations**: A list of all conversations associated with the topic.
- **Search**: A search bar to find conversations using keywords or queries.
- **Filters**: Options to filter conversations based on specific criteria.
- **Conversation Log**: A detailed log of user interactions, including the initial query and resolution, explaining why the conversation was categorized under this topic.
- **AI Insights**: Key details such as:
- Unique ID (UID) of the chat.
- User query and whether it was handled by an agent or a bot.
- Resolution status (**Resolved/Unresolved**) along with the provided resolution and reason.
- **User Sentiment** categorized as **Positive, Negative, or Neutral**, including the reason for the sentiment.
- **Debug Logs**: A record of changes made in the last **5 minutes**.
- **Comments**: A section to add comments on a specific chat or reply to existing comments, visible to others with access to the **Topics module**.
### Filter conversations
Use the **filter** icon to refine conversations based on your criteria:
- **Contained resolution**: Setting this to **True** filters conversations that are both contained and resolved. Setting it to **False** filters conversations that are either contained but unresolved, not contained but resolved, or not contained and unresolved.
- **Contained**: Filters all contained conversations, regardless of resolution status.
- **Resolved**: Filters all resolved conversations, whether contained or not.
- **User sentiment**: Filter conversations by sentiment categories such as Positive, Negative, or Neutral.
- **Automation**: Select **Available** to filter conversations whose resolutions are used for automation purposes.
### AI analytics
AI analytics consists of:
| **AI analytics** | **Description** |
|-----------------------|----------------|
| **Details** | **UID**: Unique ID of the chat. |
| |**User Query**: The initial query from the user. |
| |**Automation**: Indicates whether the conversation was handled by an agent or a bot. |
| **Resolution** | **Resolution Status**: Specifies if the conversation was **Resolved** or **Unresolved**. |
| | **Resolution Provided**: A summary of the answer given. |
| | **Resolution Reason**: LLM-generated analysis explaining why this resolution was provided. |
|**User Sentiment** | **Sentiment**: Categorized as **Positive, Negative, or Neutral**. |
| | **Sentiment Reason**: LLM-generated analysis explaining the reason behind the sentiment. |
### Debug logs
You can view logs of all changes occurring every minute. Click the debugger icon to view a particular debug log.
### Comments
You can add a new comments or reply to an existing comment. Learn more about comments [here](https://docs.yellow.ai/docs/platform_concepts/analyze/chat-logs#comments-on-conversation-logs).
> You can filter comments for **All, Open**, and **Resolved**.
---------
## Automation opportunity suggestions
The AI-agent also provides suggestions based on analyzed conversations:
- **Improve Knowledge Base**: Click **View article** to see conversations that the AI used to recommend a new knowledge base article based on human agent interaction.
- **Analyze conversations**: Click **View conversations** to identify opportunities for AI-agent improvement.
-----
## Visualized results
Key metrics such as **AI resolution rate, automation rate**, and **user sentiment** for the selected topic are displayed as graphs for the selected time period. These values, already available on the Topics page, are visualized in graph form to help you understand trends more effectively. You can view conversations pre-filtered by clicking **View conversations**.
* **AI resolution rate**: Percentage of conversations fully managed and successfully resolved by the AI Agent. View **Resolved vs. Unresolved** conversations under this category.
* **Automation Rate**: Percentage of conversations handled entirely by the AI Agent. View **AI Agent vs. Human Agent** handled conversations under this category.
* **User Sentiment**: Overall sentiment of user interactions with the AI Agent. View Conversations categorized by sentiment under this category.
---
## Topic Analysis to Enhance Automated Resolution Rates
:::note
Topics is a gated feature. Contact [yellow.ai's support team](mailto:support@yellow.ai) for more details.
:::
The **Topics** section gives you a high-level view of the different themes your AI-agent is handling in customer conversations. These topics are automatically generated based on recurring patterns in customer queries, helping you understand what your users are asking about most frequently.
Each topic represents a group of similar conversations, allowing you to track how effectively the AI-agent is resolving them. The section also highlights opportunities to improve automation by sorting topics based on **Automation Rate (AR)** opportunity. This helps you pinpoint where the AI-agent could potentially resolve more queries without needing human assistance—making your automation smarter and more efficient over time.
To **access** topics page:
1. Log in to the yellow.ai platform.
2. Open **Analyze** and navigate to **Topics**.
:::note
Conversations with fewer than three messages are not analyzed, as there isn't enough context to form a meaningful interaction.
:::
-----
## Key metrics for topic analysis
### Article suggestion
Based on the conversations AI has processed, articles are suggested for each topic with Article suggestion icon highlighted. These suggestions can serve as new additions to the existing knowledge base.
> Learn more [here](https://docs.yellow.ai/docs/platform_concepts/analyze/articlesuggestion).
### Automation opportunity
Automation Opportunity metric represents the total opportunity a topic has to improve your overall automated resolution rate. It is calculated as:
> **Automation Opportunity** = Unresolved conversations under a topic/Unresolved conversations across all topics
This helps identify which topics have the most potential for improvement.
### Conversation share
This metric shows the proportion of conversations involving a particular topic compared to all conversations:
> **Conversation Share** = Conversations under a topic/Conversations across all topics
It helps prioritize topics based on their frequency.
For example, in the below screenshot, Out of 809 conversations taken place in this AI-agent, 29 belong to this topic.
### AI resolution rate
The AI resolution rate indicates the percentage of conversations on a topic that were successfully resolved by the AI-agent without human intervention:
> **AI resolution rate** = Conversations in this topic that were contained AND resolved/Conversations in this topic
A higher AI resolution rate signifies better AI-agent performance in resolving issues autonomously.
### Automation rate
This metric measures the percentage of conversations on a topic that were not escalated to a human agent:
> **Automation Rate** = Conversations in this topic not handed over to a human agent/Conversations in this topic
A higher Automation rate indicates greater efficiency in handling the topic without needing human support.
### User sentiment
This metric assesses the sentiment of users during conversations about a specific topic. It shows the percentage of positive, negative and neutral conversations that have taken place while discussing about this topic. Understanding user sentiment helps in identifying areas where the AI-agent's responses might need improvement to enhance customer satisfaction.
----------
## Filter Topics
> By default the topics generated are filtered for the previous 30 days.
To filter data and view a particular topic, click **Filter**.
The following filters are available:
| Feature | Description | UI |
|-----------------------|-------------|---|
| **Article Suggested** | Select either "Yes" or "No." | |
| **Timestamp** | Filter data for specific dates or a custom time range. | |
| **Topics** | Filter by the text or subtext of the topics. | |
----------
## Utilize topics for AI-agent improvement
By closely monitoring these metrics, you can gain actionable insights into your AI-agent's performance and identify areas for enhancement. Here are some steps to leverage topic analysis effectively:
- **Prioritize high-opportunity topics**: Focus on topics with high Automation Opportunity to make the most significant impact on your automated resolution rate. These are the areas where improving the AI-agent's responses can yield the highest returns.
- **Analyze low Automation rate topics**: Investigate topics with low Automation rates to understand why users are being escalated to human agents. This can help in refining the AI-agent's responses or providing better training data.
- **Enhance AI Resolution Rate**: For topics with lower AI Resolution Rate, consider revising the AI-agent’s dialogue scripts, adding more detailed FAQs, or improving the AI-agent’s understanding through advanced natural language processing (NLP) techniques.
- **Monitor sentiment**: Keep an eye on user sentiment for each topic. If users consistently express negative sentiments, it’s a signal that the AI-agent’s handling of that topic needs improvement.
---
## Message view
Message view refers to how well the AI-agent has been trained to understand and respond to user input in a conversational context. It is typically evaluated by testing the AI-agent's ability to generate accurate and relevant responses to a set of input that it has not seen before.
To access this option, go to **Analyze** > **Message view**.
## 1. Filter messages
The **Filters** section lets you set the criteria based on which the utterances should be displayed.
* **Date**
Utterances that fall under this date range will be displayed.
* **Confidence range**
Confidence range is the % value based on the accuracy of the predicted Intent. Confidence score lies between 0 and 1. If the **Confidence Range** is 1, all the messages would be displayed, if it is .85, only the unidentified utterances would be displayed.
* **Small talk**
[Small talk](https://docs.yellow.ai/docs/platform_concepts/studio/train/smalltalk) responds to casual conversations with the users. Enable **Hide out of domain** to avoid displaying messages that doesn't mean anything.
Once you have set the filters, click the **Apply filter** button at the bottom to apply the changes. To reset these filters, click the **Reset filters** button.
---
## Airpay integration
Yellow.ai's integration with Airpay lets your users make payments through the AI agent. This integration enables your AI agent to generate payment links in the AI agent and share it with the AI agent users using which they can make payments.
## Prerequisites
Before you begin the integration process, make sure to retrieve the following details from your Airpay account:
1. Merchant ID
2. Access token
3. Airpay base URL
## Connect Airpay with Yellow.ai
In a two-tier environment, you can connect an integration app in the Development environment. In a three-tier environment, you can connect the integration app either in Staging or Sandbox. All connected integrations are available in the live environment.
To connect your Airpay account with Yellow.ai, follow these steps:
1. Navigate to the Development/Staging environment and go to **Extensions** > **Integrations** > **Payment** > **Airpay**.
2. In **Give account name**, enter a unique name for the integration. You can use only lowercase alphanumeric characters and underscores (_).
3. Enter the **Merchant ID**, **Access token** and **Airpay base URL**.
4. Click **Connect**.
5. To connect another account, click **+ Add Account** and proceed with the previous steps. You can add a maximum of 15 accounts.
## Generate Airpay payment link in your AI agent conversation
To generate a payment link in the AI agent using Airpay, follow these steps:
1. In Automation **Build**, open the flow where you want to add the payment link.
2. Navigate to the desired point in your conversation flow where you want to integrate with Airpay for payment links. Follow these steps:
1. Click on the Integration option in the flow editor.
2. Drag the node connector to the desired location.
3. From the Integrations menu, select Airpay.
2. Navigate to the point where you want to add the flow and click Integration >
2. At whichever point of conversation you want the AI agent to access **Airpay** for payment link, inlcude the Airpay node. For that, drag the node connector, go to **Integrations** > **Airpay**.
3. In the **Airpay** node fill in the following fields:
* **Account name:** Choose the **Airpay** account. If you have only one account, the account name is automatically populated. If you have multiple accounts, the first account added is auto-populated. Select the one you want to use at that moment.
* **Action:** Choose the action to perform, the action available for Airpay is **Generate Payment Link**.
Once you click the action, the following fields open up. There are two ways by which you can fill these fields:
**Pass dynamic data in variables**
From customers you can collect information and fill these fields. Add [prompt nodes](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes) before the integration node and [store the response of each node in a variable](https://docs.yellow.ai/docs/platform_concepts/studio/build/bot-variables#store-data-in-variables). Then, pass those variables in the respective fields here.
**Pass static values**
You type the static values in the fields by clicking **Or** or disabling **Var** option.
4. Store the JSON response of the Airpay node in a variable.
5. [Display the API response](https://docs.yellow.ai/docs/platform_concepts/studio/api/add-api-apinode#display-api-response) in a [message](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/message-nodes1/message-nodes) node.
**Sample response:**
``` jsonld
{
"success": true,
"invoice_number": "1234745234245",
"payment_url": "https://abc.invpay.co.in/invoice/OSYzMjc1NQ=="
}
```
---
## Amazon Connect Live Chat
For businesses using Amazon Connect for contact center support, the Amazon Connect Live Chat integration enables your Yellow.ai AI Agent to escalate conversations to a live Amazon Connect agent when needed. Using the **Raise Ticket** node in the agent flow, you can trigger a live chat session, allowing end users to seamlessly transition from bot-driven conversations to real-time agent support on Amazon Connect.
---
## 1. Prerequisites
Before integrating Amazon Connect Live Chat with Yellow.ai, ensure you have the following details from your AWS account:
- **[Region](#-region)**: AWS region where your Amazon Connect instance is hosted. Once you login to the console, you can see the Region ID in the Select Region and in the URL.
- **[Access Key ID & Secret Access Key](#-access-key--secret)**: IAM user credentials with appropriate Amazon Connect permissions.
- **[Instance ID](#-instance-id)**: Found in your Amazon Connect ARN.
- **[Contact Flow ID](#-contact-flow-id)**: Unique ID of the contact flow used for chat.
1. On **AWS Management**, navigate to the **Amazon Connect console**.
2. Go to the **Instances** page console and select your Connect instance.
3. On the **Routing** tab, you'll see a list of contact flows.
4. Click on the specific contact flow you want to find the ID for.
The Contact Flow ID will be part of the ARN displayed in the overview.
---
## 2. Find required AWS Parameters
### 🌍 Region
To find the **AWS Region** (specifically for your Amazon Connect instance), follow these steps:
#### Option 1: From the Amazon Connect Console
1. **Go to** the [Amazon Connect console](https://console.aws.amazon.com/connect/).
2. On the **Instances** page, locate your instance.
3. The **Region** is shown in the URL and instance details.
For example:
```
https://.awsapps.com/connect/home
```
* If the URL is `https://my-support.awsapps.com/connect/home`, the region can often be inferred from the instance's full ARN (see below).
#### Option 2: From the Instance ARN
1. In the Amazon Connect console, go to your instance's **Account overview**.
2. Copy the **Instance ARN**.
Example:
```
arn:aws:connect:us-east-1:123456789012:instance/abcd1234-ef56-gh78-ij90-klmnopqrstuv
```
3. The **third segment** in the ARN (`us-east-1`) is the **Region** where your instance is hosted.
**Region examples**
| Region Name | Region Code |
| --------------------- | -------------- |
| US East (N. Virginia) | `us-east-1` |
| US West (Oregon) | `us-west-2` |
| Asia Pacific (Mumbai) | `ap-south-1` |
| Europe (Frankfurt) | `eu-central-1` |
:::note
* [Find your Amazon Connect instance ID and region (AWS Docs)](https://docs.aws.amazon.com/connect/latest/adminguide/find-instance-arn.html)
:::
### 🔐 Access Key & Secret
To generate an access key and secret for an IAM user:
1. Sign in to the [AWS Management Console](https://console.aws.amazon.com/iam/) as an IAM user with appropriate permissions.
2. Navigate to **IAM** → **Users**.
3. Select the desired user.
4. Go to the **Security credentials** tab.
5. Under **Access keys**, click **Create access key**.
6. Choose **Command Line Interface (CLI)** as the use case.
7. Click **Next**, then **Create access key**.
8. Download and securely store the access key ID and secret access key.([AWS Documentation][1], [AWS Documentation][2])
:::note
* It is recommended to avoid using root user credentials for daily tasks. If necessary, root users can create access keys by navigating to **My Security Credentials** in the AWS Console and selecting **Create access key** under the **Access keys** section. ([AWS Documentation][3])
:::
---
### 🆔 Instance ID
To locate your Amazon Connect Instance ID:
1. Open the [Amazon Connect console](https://console.aws.amazon.com/connect/).
2. On the **Instances** page, select your instance alias.
3. On the **Account overview** page, in the **Distribution settings** section, find the **Instance ARN**.
4. The Instance ID is the segment following `instance/` in the ARN.([AWS Documentation][4])
*Example ARN:*
```
arn:aws:connect:us-east-1:123456789012:instance/abcd1234-ef56-gh78-ij90-klmnopqrstuv
```
*Here, `abcd1234-ef56-gh78-ij90-klmnopqrstuv` is the Instance ID.*
---
### 🔁 Contact Flow ID
To create Contact Flow ID, you need to have the contact flow and the Amazon Connect instance in the same AWS Region to avoid region conflicts.
To retrieve the Contact Flow ID:
1. Sign in to the [Amazon Connect console](https://console.aws.amazon.com/connect/) with an Admin account or an account assigned to a security profile that has permissions to view contact flows.
2. In the navigation pane, choose **Routing**, then **Contact flows**.
3. Select the desired contact flow.
4. Click **Show additional flow information** to view the Flow ID.([AWS Documentation][6])
[1]: https://docs.aws.amazon.com/cli/v1/userguide/cli-authentication-user.html?utm_source=chatgpt.com "Authenticating using IAM user credentials for the AWS CLI"
[2]: https://docs.aws.amazon.com/keyspaces/latest/devguide/access.credentials.IAM.html?utm_source=chatgpt.com "Create an IAM user for programmatic access to Amazon Keyspaces ..."
[3]: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html?utm_source=chatgpt.com "Manage access keys for IAM users - AWS Documentation"
[4]: https://docs.aws.amazon.com/connect/latest/adminguide/find-instance-arn.html?utm_source=chatgpt.com "Find your Amazon Connect instance ID or ARN"
[5]: https://docs.aws.amazon.com/connect/latest/APIReference/API_DescribeInstance.html?utm_source=chatgpt.com "DescribeInstance - Amazon Connect"
[6]: https://docs.aws.amazon.com/connect/latest/adminguide/find-contact-flow-id.html?utm_source=chatgpt.com "Find the flow ID when integrating Apple Messages for Business with ..."
---
## 3. Integrate Amazon Connect with Yellow.ai
1. Log into your Yellow.ai bot and switch to the appropriate environment (Development/Staging/Sandbox).
2. Navigate to **Extensions** > **Integrations** > **Live Chat** > **Amazon Connect Live Chat**.
3. Configure the following fields to integrate **Amazon connect live chat**:
| Field Name | Description |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| **Account Name** | A unique name for the Amazon Connect account. Use only lowercase alphanumeric characters and underscores (_). The same name will be used in the production environment as well. Example value: `support_team_account` |
| **[Region](#-region)** | The AWS region where your Amazon Connect instance is hosted. Example value: `us-east-1` |
| **[Access Key ID](#-access-key--secret)** | AWS access key ID for an IAM user with required permissions for Amazon Connect. Example value: `AKIAIOSFODNN7EXAMPLE` |
| **[Secret Access Key](#-access-key--secret)** | AWS secret access key corresponding to the above key. Keep this confidential. Example value: `wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY` |
| **[Contact Flow ID](#-contact-flow-id)** | The ID of the contact flow that defines the chat experience.Example value: `12345678-1234-1234-1234-123456789012` |
| **[Instance ID](#-instance-id)** | Unique identifier of your Amazon Connect instance. Example value: `abcd1234-ef56-gh78-ij90-klmnopqrstuv` |
| **Polling Timeout (ms)** | Time in milliseconds to wait for a response before timing out (before auto-closing chat). Example value: `30000` |
| **Chat Duration (minutes)** | Maximum time in minutes that a chat session can remain active. (default: 25 hours, configurable: 60–10,080 minutes) Example value: `60` |
4. Click **Connect**. You can connect up to 15 accounts in total.
---
## 4. Connect your Amazon Connect Live Chat account to your AI agent
To Configure Connect Live Chat in your AI agent conversation:
1. In the Automation module, go to [Build](https://docs.yellow.ai/docs/platform_concepts/studio/build/Flows/journeys).
2. Navigate to the flow where you want to add the live agent flow and insert **Raise a ticket** node (**Integration** > **Raise a ticket**).
3. In **Live chat agent**, select **Amazon connect live chat**.
4. Configure the following details:
| **Option** | **Description** |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| **Account name** | Select the account you want to associate with the live chat. |
| **Message after ticket assignment** | Enter the message to be sent automatically once the ticket is assigned to a live agent. |
| **Name** | Provide a label or identifier for the ticket. This helps categorize and reference it easily. |
| **Mobile** | Select the mobile number associated with the ticket. Useful for contacting the user if needed. |
| **Email** *(Optional)* | Select the email address linked to the ticket, if applicable. |
| **Query** | Select the variable where you want to capture the user's query |
| **Amazon connect live agent custom fields*** | Select the object variable to pass custom field values to live agents. Example: ```{"ticketId": "hello"}``` |
5. To customize how your tickets are handled and processed, you can enable and configure **Advanced options**. These options allow you to set ticket priority, enable auto-translation, and add custom fields, tags, and departments.
---
## App store Integration
Effortlessly manage user ratings and reviews directly from your bot by integrating with your Apple App Store account. This integration requires access to App Store Connect and your iOS app deployed on the App Store.
Our integration supports all versions compatible with the Apple App Store.
## Connect your App Store to yellow.ai bot
Before integrating your App Store account with Yellow.ai, ensure your App Store Connect account and iOS app are ready as detailed [here](https://developer.apple.com/documentation/appstoreconnectapi).
### Authenticate Yellow.ai to access App Store
1. On the Staging/Development environment, go to **Extensions** > **Integrations** > **Tools & Utilities** > **App store**. You can also search for App store in the Search box.
2. In **Give account name**, enter a unique name for the integration.It supports only lowercase, alphanumeric characters, and underscores (_).
3. In **Application ID**, enter the unique identifier assigned to your iOS application within the Apple App Store. This ID is essential for linking your app to the Yellow.ai bot.
4. In **Private key**, enter a secure cryptographic key used for authentication and authorization purposes in API communications between your bot and the respective app store's backend services. It ensures secure and encrypted data transmission.
5. In **API key**, enter a unique identifier used to authenticate requests made to the app store's APIs. It acts as a credential to access and interact with various services provided by the app store, such as managing user ratings, reviews, and other app-related data.
6. In **Issuer ID**, enter the identifier that uniquely identifies the entity or organization that issued the credentials. It helps validate the authenticity and permissions associated with the keys used for accessing app store APIs and services.
7. Click **Connect**.
8. To connect another account, click **+ Add Account** and proceed with the previous steps. You can add a maximum of 15 accounts.
---
## Atlassian
The Atlassian integration with Yellow.ai enables you to manage Atlassian activities, allowing your bot to provide users with access to their Atlassian account and perform Atlassian actions directly within the Yellow.ai bot.
## Steps to integrate with Yellow.ai
The following are the steps to be followed to integrate your Atlassian account with Yellow.ai.
### Create an app on Atlassian
1. Go to https://developer.atlassian.com/console/myapps/ and click **Create** > **Oauth 2.0 integration**.
2. Go to **Console** > **My apps** > **yourAppName** > **Permission** > **Jira API** > **Add** > **Configure**.
3. Add configure the app’s API scopes for JIRA.
**Common permissions**
| Scope | Description |
| --- | --- |
| read:jira-work | Read access to Jira project and issue information, and search for specific issues. |
| read:jira-user | Read access to Jira user information that is available to you. |
| write:jira-work | Create and edit access to Jira issues, including creating and editing them, posting comments on behalf of the user, adding worklogs, and deleting issues. |
| read:servicedesk-request | Read access to customer requests data, including approvals, attachments, comments, and request participants. |
| write:servicedesk-request | Create and edit access to customer requests, including creating and editing them, adding comments and attachments. |
4. Go to https://cloud.yellow.ai > **Extensions** > **Integrations**, and click the URL hyperlink to copy it copy it.
6. Paste this in the **Callback URL** field.
5. Go to **Settings** and copy the **Client ID** and **Secret**.
### Connect Atlassian with Yellow.ai
1. On the [Cloud platform](https://cloud.yellow.ai), navigate to Development/Staging environment and go to **Extensions** > **Integrations** > **Tools & Utilities** > **Atlassian**. Alternatively, you can use the Search box to find a specific integration.
2. In **Give account name**, enter a unique name for the integration. You can use only lowercase alphanumeric characters and underscores (`_`).
3. Enter **Client ID**, **Client secret** to access Atlassian account.
4. Add the list of **Scopes** for the integration, separate each scope with space.
> For example: scope": "offline_access read:jira-work read:jira-user write:jira-work read:servicedesk-request write:servicedesk-request
5. Click **Connect**.
6. To connect another account, click **+ Add account** and proceed with the previous steps. You can add a maximum of 15 accounts.
## Manage Atlassian actions through bot conversations
The Atlassian integration enables bot to perform the following actions:
### Enable Atlassian events in Automation
1. Open your cloud platform and navigate to the Development/Staging environment.
2. Go to **Automation** > **Event** > **Custom events** and create a custom event named `atlassian-auth-success`. Click [here](https://docs.yellow.ai/docs/platform_concepts/studio/events/event-hub#custom-events) for the steps to create custom event.
3. You can set this event as a [start trigger for a flow](https://docs.yellow.ai/docs/platform_concepts/studio/build/Flows/configureflow#trigger-flow-using-event). This flow will get triggered after a user is successfully authorized. [Build the flow](https://docs.yellow.ai/docs/platform_concepts/studio/build/Flows/journeys) to execute the desired action immediately after the user's authorization.
### Managing Atlassian actions through bot conversations
1. In the Development/Staging environment, go to **Automation** > **Build** > and [flow](https://docs.yellow.ai/docs/platform_concepts/studio/build/Flows/journeys) where you want to access Atlassian functions.
2. When adding a node, choose **Integrations** > **Atlassian**.
#### Generate Atlassian login URL
To display the URL to the user, pass this variable in a message node in this syntax `{{variables.variable.arrayname.fieldname}}`.
**Sample response**
```json
{
"success": true,
"message": "Login URL Generated Successfully.",
"data": {
"AtlassianLoginUrl": "https://auth.atlassian.com/authorize/consent?context=eyJraWQiOiJiOWY2OTVlZmM3MzgwN2QxNmNhNmNkMzQiLCJhbGciOiJSUzI1NiIsInR5cCI6Imp3dCJ9.eyJuYmYiOjE2NzY1NDA3OTgsImlzcyI6ImF1dGguYXRsYXNzaWFuLmNvbSIsImlhdCI6MTY3NjU0MDc5OCwiZXhwIjoxNjc2NTQ0Mzk4LCJhdWQiOiJhcGkuYXRsYXNzaWFuLmNvbSIsInVzZXJfaWQiOiI2MjgzNTUwNGNjMWQxNTAwNmZhOWU3NjkiLCJyZWRpcmVjdF91cmkiOiIvYXV0aG9yaXplP2F1ZGllbmNlPWFwaS5hdGxhc3NpYW4uY29tJmNsaWVudF9pZD1hMEthSUpGM2pTN0dvWGhjYmJZNkNuWEphaGtPczlXRSZzY29wZT1yZWFkJTNBamlyYS13b3JrJTIwb2ZmbGluZV9hY2Nlc3MmcmVkaXJlY3RfdXJpPWh0dHBzJTNBJTJGJTJGY2FjNy0yNDAxLTQ5MDAtMWMyOC0yMzIxLWU1MmYtZDRlZS04M2JkLTQzN2UuaW4ubmdyb2suaW8lMkZjYWxsYmFjayZzdGF0ZT0xMjMmcmVzcG9uc2VfdHlwZT1jb2RlJnByb21wdD1jb25zZW50IiwiY2xpZW50Ijp7ImNsaWVudF9pZCI6ImEwS2FJSYzalM3R29YaGNiYlk2Q25YSmFoa09zOVdFIiwibmFtZSI6IlllbGxvdy1NYXJrZXRwbGFjZSIsImxvZ29fdXJpIjoiaHR0cHM6Ly9hdmF0YXItbWFuYWdlbWVudC"
}
}
```
#### Refresh access token on Yellow.ai
Choose the variable that contains **Refresh token**.
| Field name| Data type | Description | Sample value |
| ------------ | --------- | --------- | ------------ |
| Refresh Token | String | Access and refresh token obtained from Atlassian event after successful login. | asddskeku2iwewbhwjsnmelsdjckmd22eokeds |
**Sample success response:**
```json
{
"access_token": "eyJraWQiOiJmZTM2ZThkMzZjMTA2N2RjYTgyNTg5MmEiLCJhbGciOiJSUzI1NiJ9.-sHvWY5wAsrRuvzgOJ-ImZlQXPKnz_-Mv4K70aHwVkpbE8sLXovfoo2gIZZ2mgsTKzeVQ_YcKX0EMPTnuViXMoDwm1RfwHb",
"expires_in": 3600,
"token_type": "Bearer",
"refresh_token": "eyJraWQiOiI1MWE2YjE2MjRlMTQ5ZDFiYTdhM2VmZjciLCJhbGciOiJSUzI1NiJ9.eyJqdGkiOiI5NDg3ZWM5My1iZDk5LTQ4YTctODNiMi02YWNjMmE4ODlmNDgiLCJzdWIiOiI2MjgzNTUwNGNjMWQxNTAwNmZ",
"scope": "manage:jira-configuration manage:jira-project offline_access read:jira-user"
}
```
---
## Avaya Live Chat
Yellow.ai’s integration with [Avaya](https://www.avaya.com/en/) lets you connect with the live chat agents of **Avaya** to resolve your queries.
## 1. Connect Avaya with Yellow.ai
To connect your yellow.ai account with **Avaya**, follow these steps.
### 1.1 Enable the integration in Yellow.ai's **Integration** module
1. Login to [cloud.yellow.ai](https://cloud.yellow.ai/auth/login) and click the **Integrations** module on the top left corner of your screen.
2. Search for **Avaya Live Chat** or choose the category named **Live chat** from the left navigation bar and then click on **Avaya Live Chat**.
3. Fill in the required fields.
* **Avaya Username Name** (To be provided by the client/avaya spoc of the client)
* **Avaya Password** (To be provided by the client/avaya spoc of the client)
* **Api Domain** (To be provided by the client/avaya spoc of the client).
4. Once you're done, click **Connect**.
5. If you have multiple accounts, follow the above mentioned steps to add each of them.
:::note
1. Enter a unique name for each account to easily identify them within the yellow.ai platform. It is recommended to use a name that aligns with its purpose for better usability.
2. You can add a maximum of 5 merchant accounts.
3. In a two-tier environment, such as bots with only Development/Live environments, you can add account names only in the development mode. Once added and flows have been built, in the Live mode, you can only choose the account names and not edit them.
4. In a three-tier environment, such as bots with Staging/Sandbox/Production modes, in Staging and Sandbox modes, you can add and edit new accounts. However, in Production, only the account details added in Staging will be available. You can only map in the production environment.
:::
### 1.2 Configure webhook URL in Avaya Dashboard
To receive events, you need to configure the webhook URL in the **Avaya Dashboard**.
Copy the webhook url and the api key mentioned in the **Instructions** section of the **Avaya Integration** Card. Append the region of your bot to the domain of the webhook url. r1/r2/r3/r4/r5 are the regions of your bot, you can refer the following list for the same.
* r1 = MEA
* r2 = Jakarta
* r4= USA
* r5 = Europe
* r3 = Singapore
For example, if the domain is https://cloud.yellow.ai, you need to change it to https://r1.cloud.yellow.ai if the region of the bot is r1. If the bot belongs to India, you can use origin domain itself.
## 2. Use-case
This integration lets you connect with live agents on the **Avaya** platform from your yellow.ai account.
:::note
When multiple accounts are added, select the appropriate account for each node, allowing you to leverage the unique functionalities of each account for their intended purposes.
:::
### 2.1 Chat with Avaya Live Agent
:::info
Use **Ticket-closed** in the **Raise Ticket node** to perform specific actions when a live chat closes, instead of using the **ticket-close** event.
:::
1. In the Automation flow builder, select the **Raise Ticket** node.
2. Select **Avaya Live Chat** from the **Live chat agent** drop-down list.
The following table contains the details of each field of the **Raise ticket** node.
| Field name | Sample value | Data type |Description
| -------- | -------- | -------- |-----|
|Message after ticket assignment|Requesting live agent connection.|String| The message that will be displayed to the end user after a ticket is successfully assigned to an agent|
|Name| Rajesh|String|Name of the end user|
|Mobile| 9870000000| String|Mobile number of the end user|
Email|test@gmail.com|String|Email address of the end user
Query|I have a concern regarding my flight ticket|String| The subject/topic/reason why the ticket was created|
Priority|MEDIUM|String|The priority of the ticket|
You can enable **Advanced Options** to access the advanced features of this node.
**Sample success response**
```
{
"assignedTo": true,
"success": true,
"status": "ASSIGNED",
"ticketInfo": "{{apiresponse}}"
}
```
:::note
apiresponse represents the raw response from the Avaya create ticket API
:::
**Sample failure response**
```
{
"success": false,
"assignedTo": false,
"agentNotAvailable": true,
"message": "TicketId is not created and transferring the control back to the bot",
"ticketInfo": "{{apiresponse}}"
}
```
:::note
apiresponse represents the raw response from the Avaya create ticket API
:::
---
## AWS-S3 integration
Integration of AWS S3 with Yellow.ai enables your bot to access remote files, create and delete buckets, upload files, obtain a signed URL for a file, and delete files from the bucket from AWS account.
## Connecting your AWS S3 account with Yellow.ai
Configuring the integration with AWS S3 is straightforward. Follow the steps defined below to start integrating:
**To integrate AWS S3 with your bot on the platform:**
1. AWS Account and Access Keys
* Open the IAM console at https://console.aws.amazon.com/iam/.
* On the navigation menu, choose Users
* Choose your IAM user name (not the check box).
* Open the Security credentials tab, and then choose Create access key.
* To see the new access key, choose Show. and Copy the Access Key Id and Secret Access Key.
* Go to IAM > User > click on your user profile > Add Permission > Add AmazonS3FullAccess Policy.
2. On the Cloud platform, navigate to Development/Staging environment and go to **Extensions** > **Integrations** > **Tools & Utilities** > **AWS S3**. Alternatively, you can use the Search box to find a specific integration.
3. In **Give account name**, enter a unique name for the integration. You can use only lowercase alphanumeric characters and underscores (`_`).
4. Enter **Access Key Id** and **Access Secret Key**.
5. In Location, specify the location or region where your AWS S3 bucket is hosted. This ensures that the integration connects to the correct AWS region where your data is stored. For example: `us-east-1` (Northern Virginia), `eu-west-1` (Ireland), or `ap-southeast-1` (Singapore).
5. Click **Connect**.
6. To connect another account, click **+ Add account** and proceed with the previous steps. You can add a maximum of 15 accounts.
## Manage AWS S3 actions through bot conversations
The AWS integration enables bot to perform the following actions:
Once the integration is successful, you can perform the following actions in bot conversations.
1. Go to Development/Staging environment and navigate to **Automation** > **Build** > Select the flow where you want to add action node.
2. Click **Add node** > **Integrations** > **AWS S3**.
3. In **Account name**, select the account from which you'd like to perform the action. This is applicable for integrations with multiple accounts.
### 1. Upload File
This lets you upload files to the AWS bucket.
**Node Input Params**
|Field Name|Sample Input|Remarks|
|--- |--- |--- |
|fileCdnUrl*|https://cdn.pixabay.com/photo/2017/01/03/02/07/vine-1948358__340.png|Data source for data to copy to the remote server.|
|remoteFilePath*|/uploads/directoryPath/demo.png|Path to the Bucket to be created on the Bucket with file name.|
|bucketName*|your_bucket_name|The name of the bucket where upload the file|
### 2. List Objects
Returns some or all (up to 1,000) of the objects in a bucket.
**Node Input Params**:
|Field Name|Sample Input|Remarks|
|--- |--- |--- |
|bucketName*|Your_Bucket_Name|The name of the bucket containing the objects.|
### 3. Delete File
Deletes an object from an S3 bucket.
**Node Input Params**:
|Field Name|Sample Input|Remarks|
|--- |--- |--- |
|remoteDirPath*|/folder/demo.ong|Key name of the object to delete.|
|bucketName|Your_Bucket_Name|The bucket name of the bucket containing the object.|
### 4. Bucket Lists
Returns a list of all buckets owned by the authenticated sender of the request. To use this operation, you must have the s3:ListAllMyBuckets permission.
### 5. Get Object
Retrieves objects from Amazon S3. To use GET, you must have READ access to the object.
**Node Input Params**:
|Field Name|Sample Input|Remarks|
|--- |--- |--- |
|remotefilePath*|photos/2006/February/sample.jpg|To get an object from such a logical hierarchy, specify the full key name for the object in the GET operation|
|bucketName*|Your_Bucket_Name|The bucket name of the bucket containing the object.|
### 6. Create Bucket
Creates a new S3 bucket. To create a bucket, you must register with Amazon S3 and have a valid AWS Access Key ID to authenticate requests
**Node Input Params**:
|Field Name|Sample Input|Remarks|
|--- |--- |--- |
|bucketName*|Your_Bucket_Name|The bucket name of the bucket where you will store the objects.|
### 7. Get Signed URL
Get a pre-signed URL for a given file.
**Node Input Params**:
|Field Name|Sample Input|Remarks|
|--- |--- |--- |
|remoteFilePath*||remote directory path|
|bucketName|Your_Bucket_Name|The bucket name of the bucket containing the object.|
|expire|60|Expire time of url in seconds.|
#### Note: If you open the signed Url in browser, then It will take extra 40-60 sec to given expiry time due to browser's cache mechanism.
# **References:-**
1. [https://docs.aws.amazon.com/powershell/latest/userguide/pstools-appendix-sign-up.html](https://docs.aws.amazon.com/powershell/latest/userguide/pstools-appendix-sign-up.html)
2. [https://docs.aws.amazon.com/AmazonS3/latest/API/API_Operations.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_Operations.html)
---
## Azure AD integration
Azure Active Directory (Azure AD) enhances user management by enabling **Single Sign-On (SSO)** and personalized app experiences through the use of organizational data APIs. This integration also offers IT administrators comprehensive control over application and resource access, using advanced security features like **Multi-Factor Authentication (MFA)** and conditional access.
#### Key Features:
- **SSO for Seamless Access:** Azure AD supports integration with over 2,800 pre-configured Software as a Service (SaaS) applications, simplifying access management across systems.
- **Security and Personalization:** Use organization-specific data to create secure, tailored experiences.
#### Yellow.ai Compatibility:
Yellow.ai comes pre-integrated with:
- **Active Directory Federation Services (ADFS)**
- **Generic OAuth** implementation
This ensures secure authentication while supporting diverse organizational needs.
#### Authentication Flow:
When ADFS is enabled:
1. The bot redirects you to the **Active Directory login page** for credential input.
2. AD validates the credentials.
3. Upon successful authentication, ADFS triggers a callback to Yellow.ai to indicate the result.
4. If authentication succeeds, ADFS generates:
- An **authentication token**
- A **refresh token**
- The token’s **time-to-live (TTL)**
These tokens allow secure access while maintaining control over session duration.
---
## **App Registration on Azure AD**
To connect Azure AD with your Yellow.ai bot, you must first register an app in Azure AD and retrieve the following details:
1. **Client ID** (Application ID)
2. **Tenant ID**
3. **Client Secret**
### **Steps to Configure the App in Azure AD**
1. Log in to [Azure Portal](https://portal.azure.com) and navigate to **Active Directory** > **App Registrations**.
2. [Register a new application](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app?tabs=certificate) for the chatbot (if not already registered).
3. Copy and save the **Application/Client ID** and **Tenant ID** from the **Overview** section.
4. Navigate to **Certificates & Secrets**:
- Click **New Client Secret**.
- Provide a description and set the expiration to **Never**.
- Click **Add**, and copy the generated Client Secret for future use.
5. Go to **Authentication**:
- Click **Add a Platform** > **Web**.
- Add the Redirect URL:
`https://app.yellowmessenger.com/integrations/azureauth/`
- Click **Save**.
6. Configure Permissions:
- Navigate to **API Permissions** > **Add Permission**.
- Add the following common permissions and grant **Admin Consent**:
| **Scope** | **Description** |
|---------------------|--------------------------------------------------------------|
| openid, email, profile, User.Read | Retrieve login details and user profiles using Graph API. |
| offline_access | Required for refresh token retrieval. |
| User.Read.All | Read user profiles in the tenant. |
| Calendars.ReadWrite | Modify user calendars and meetings. |
For more details, refer to the [Graph Permissions Guide](https://docs.microsoft.com/en-us/graph/permissions-reference).
---
### **Steps to Integrate Azure App with Yellow.ai Bot**
1. In the Yellow.ai platform, navigate to the **Development** or **Staging** environment:
- Go to **Extensions** > **Integrations** > **Tools & Utilities** > **Azure**.
- Use the search box if needed.
2. In the **Account Name** field, provide a unique name for the integration (use lowercase alphanumeric characters and underscores only).
3. Enter the following details obtained from Azure AD:
- **Tenant ID**
- **Client ID**
- **Client Secret**
4. Set the API version to **v2.0**.
5. Specify the required **Scope** (e.g., `Calendars.ReadWrite offline_access User.Read`).
6. Click **Connect**.
7. To connect additional accounts, click **+ Add Account** and repeat the steps above. A maximum of 15 accounts can be added.
---
### **Authentication Workflow**
When a user initiates authentication via Azure AD:
1. The bot redirects the user to the **Active Directory login page**.
2. After entering their credentials, AD validates them.
3. Upon successful authentication, Azure AD sends a callback to Yellow.ai with:
- **Access Token**
- **Refresh Token**
- **Token Expiry Details**
#### **Access Token Usage**
The **Access Token** allows secure access to resources within the permissions granted. Note: Tokens expire in 1 hour but can be refreshed using the **Refresh Token** for up to 90 days.
---
### Retrieve User Profile via Graph API
To fetch user details using the **Access Token**, send a GET request to the Microsoft Graph API:
#### Request:
{`curl --location --request GET 'https://graph.microsoft.com/v1.0/me' \\
--header 'Authorization: Bearer {accessToken}'`}
#### Response Example:
```json
{
"@odata.context": "[https://graph.microsoft.com/v1.0/$metadata#users/$entity](https://graph.microsoft.com/v1.0/$metadata#users/$entity)",
"businessPhones": [],
"displayName": "Shubhi Saxena",
"givenName": "Shubhi",
"jobTitle": null,
"mail": "shubhi@bitonictexxxxxxx.onmicrosoft.com",
"mobilePhone": null,
"surname": "Saxena",
"userPrincipalName": "shubhi@bitonictexxxxxxx.onmicrosoft.com",
"id": "e4a5dbe5-4750-41e7-8axxxxxxxxx"
}
```
### **Other Useful Graph APIs**
1. [Get User Events](https://docs.microsoft.com/en-us/graph/api/user-list-events?view=graph-rest-1.0&tabs=http)
2. [Send Email on Behalf of a User](https://docs.microsoft.com/en-us/graph/api/user-sendmail?view=graph-rest-1.0&tabs=http)
3. [Retrieve User Tasks](https://docs.microsoft.com/en-us/graph/api/planneruser-list-tasks?view=graph-rest-1.0&tabs=http)
4. [Update Password](https://docs.microsoft.com/en-us/graph/api/resources/passwordprofile?view=graph-rest-1.0)
---
### **Resources for Exploration**
- [Microsoft Graph API Documentation](https://docs.microsoft.com/en-us/graph/api/overview?view=graph-rest-1.0)
- [Graph Explorer](https://developer.microsoft.com/en-us/graph/graph-explorer)
---
This version ensures clarity, professionalism, and adherence to documentation standards. It is structured for easy navigation and a seamless user experience.
## App Registration on AAD
For connecting Azure AD with YM bot, following details need to be obtained using AD App registration:
1. Client ID / Application ID
2. Tenant ID
3. Client Secret
## Steps to configure App in Azure AD
1. Go to [portal.azure.com](https://portal.azure.com/) > Active Directory > App Registrations.
2. [Register a new app](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app?tabs=certificate) for the chatbot (if not already registered)
3. Copy and Save the Application/Client ID and tenant ID from overview section.
4. Go to Certificates & Secrets > New client secret > Fill the description & select expires to Never, After clicking on Add button a Client Secret will be generated, save the value of the Client Secret.
5. Goto **Authentication** > **Add a platform** > **Web** > **Add the redirect URL** > **Save**.
Redirect-Url: `https://app.yellowmessenger.com/integrations/azureauth/`
6. Add/Remove permission and Grant Admin consent for the App.
7. Go to API Permissions > Add the required permissions.
**Common permission:**
| Scope | Description |
| --------------------------------- | -------------------------------------------------------------- |
| openid, email, profile, User.Read | Used to retrieve login details & their profile using Graph Api |
| offline_access | Required to obtain refresh token |
| User.Read.All | Read profile of all the user in the tenant. |
| Calendars.ReadWrite | Edit User’s calendar / meetings |
Graph Permission: https://docs.microsoft.com/en-us/graph/permissions-reference
## Steps to integrate Azure app with yellow.ai bot:
1. On the Cloud platform, navigate to Development/Staging environment and go to **Extensions** > **Integrations** > **Tools & Utilities** > **Azure**. Alternatively, you can use the Search box to find a specific integration.
2. In **Give account name**, enter a unique name for the integration. You can use only lowercase alphanumeric characters and underscores (`_`).
3. Enter the obtained **Tenant ID**, **Client ID**, **Client Secret**.
3. Enter the API version to v2.0
4. Enter the required scope.
5. Click **Connect**.
5. If you want to connect multiple accounts, click **+ Add account** and proceed with the previous steps. You can add a maximum of 15 accounts.
### **Obtain Azure AD Login URL**
```js
let consent = "&prompt=login"; // prompt=login allows user to choose a login account
{
"title": "Login",
"url": app.azure.auth() + consent
}
```
---
### **Response**
```js
app.log(app.data);
{
"event": {
"code": "azure-auth-success",
"data": {
"token_type": "Bearer",
"scope": "Calendars.ReadWrite email openid profile User.Read",
"expires_in": 3599,
"ext_expires_in": 3599,
"access_token": "eyJ0eXXXXXXXXXXXXXXXXX",
"refresh_token": "aiJ0eXXXXXXXXXXXXXXXX"
}
}
}
```
---
**Access Token** can be used to access resources of allowed applications.
**Expires in:** 1 hour.
Azure allows an expired access token to be refreshed using the **Refresh Token** for up to **90 days**.
---
### **Retrieve User Profile using Azure AD Access Token**
#### Request
```bash
curl --location --request GET 'https://graph.microsoft.com/v1.0/me' \
--header 'Authorization: Bearer `{{accessToken}}`'
```
#### Response
```json
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users/$entity",
"businessPhones": [],
"displayName": "Shubhi Saxena",
"givenName": "Shubhi",
"jobTitle": null,
"mail": "shubhi@bitonictexxxxxxx.onmicrosoft.com",
"mobilePhone": null,
"surname": "Saxena",
"userPrincipalName": "shubhi@bitonictexxxxxxx.onmicrosoft.com",
"id": "e4a5dbe5-4750-41e7-8axxxxxxxxx"
}
```
**Other useful Graph APIs:**
1. [Get events of user](https://docs.microsoft.com/en-us/graph/api/user-list-events?view=graph-rest-1.0&tabs=http)
2. [Send email on behalf of user](https://docs.microsoft.com/en-us/graph/api/user-sendmail?view=graph-rest-1.0&tabs=http)
3. [Load tasks of user](https://docs.microsoft.com/en-us/graph/api/planneruser-list-tasks?view=graph-rest-1.0&tabs=http)
4. [Update password](https://docs.microsoft.com/en-us/graph/api/resources/passwordprofile?view=graph-rest-1.0)
**Graph APIs:**
[https://docs.microsoft.com/en-US/graph/api/overview?view=graph-rest-1.0](https://docs.microsoft.com/en-US/graph/api/overview?view=graph-rest-1.0)
**Graph Explorer:** [https://developer.microsoft.com/en-us/graph/graph-explorer](https://developer.microsoft.com/en-us/graph/graph-explorer)
## References
1. [Azure ADFS](https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/overview/whats-new-active-directory-federation-services-windows-server)
2. [Active Directory authentication](https://docs.microsoft.com/en-us/microsoftteams/platform/tabs/how-to/authentication/auth-flow-tab)
3. [Graph APIs](https://docs.microsoft.com/en-US/graph/api/overview?view=graph-rest-1.0)
4. [App Registration](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app)
---
## Bamboo HR
Yellow.ai's integration with BambooHR allows you to connect your BambooHR account directly to your agent, enabling it to perform real-time HR operations — from fetching employee profiles and managing time-off requests to terminating employees and uploading documents — without leaving the conversation.
:::tip What can you build with this?
Common use cases include an **employee self-service agent** (check leave balance, apply for time-off, update emergency contacts), an **HR ops agent** (onboard new hires, update job info, fetch employment status), and a **manager assistant agent** (approve/deny time-off, view who's out, check team benefits).
:::
## Supported Actions
| Action | Description |
| -------- | -------- |
| [Fetch Employee Information](#fetch-employee-information) | Fetches full employee profile using the employee ID. |
| [Fetch Employee Time-Offs](#fetch-employee-time-offs) | Fetches time-off requests for an employee within a date range. |
| [Apply Time-Offs](#apply-time-offs) | Submits a new time-off request on behalf of an employee. |
| [Update Time-Offs](#update-time-offs) | Approves, denies, or cancels a time-off request by request ID. |
| [Update Employee](#update-employee) | Updates one or more profile fields for an existing employee. |
| [Create Employee](#create-employee) | Creates a new employee record in BambooHR. |
| [Upload Document](#upload-document) | Uploads a document to an employee's file in BambooHR. |
| [View Company Benefits](#view-company-benefits) | Retrieves all company-level benefit coverage types. |
| [View Employee Benefits](#view-employee-benefits) | Retrieves payroll deduction and benefit enrollment details for an employee. |
| [View Employee Remaining Time-Offs](#view-employee-remaining-time-offs) | Fetches current leave balance across all time-off policies for an employee. |
| [View Time-Off Types](#view-time-off-types) | Retrieves all time-off types configured in the company's BambooHR account. |
| [View Emergency Contact Details](#view-emergency-contact-details) | Fetches emergency contact records for an employee. |
| [Add Emergency Contact Details](#add-emergency-contact-details) | Adds a new emergency contact for an employee. |
| [Update Emergency Contact Details](#update-emergency-contact-details) | Updates an existing emergency contact record. |
| [Get Job Info History](#get-job-info-history) | Retrieves the full job information history for an employee. |
| [Add Job Info Row](#add-job-info-row) | Adds a new job info entry (e.g., promotion, transfer) for an employee. |
| [Get Who's Out](#get-whos-out) | Lists all employees on approved leave within a given date range. |
| [Terminate Employee](#terminate-employee) | Records an employee termination in BambooHR. |
| [Fetch Employee Employment Status](#fetch-employee-employment-status) | Retrieves the employment status history for an employee. |
| [Get Custom Fields Schema](#get-custom-fields-schema) | Fetches all custom employee fields defined in your BambooHR account. |
---
## Integrating BambooHR with Yellow.ai
In a two-tier environment, you can connect an integration app in the Development environment. In a three-tier environment, you can connect the integration app either in Staging or Sandbox. All connected integrations are available in the live environment.
To integrate Yellow.ai with BambooHR, follow the steps below:
1. Switch to the Development/Staging environment and go to **Extensions** > **Integrations** > **HR** > **Bamboo HR**. Alternatively, use the Search box to quickly find the required integration.
2. In **Give account name**, enter a unique name for the integration. You can use only lowercase alphanumeric characters and underscores (_).
3. Enter your account's **Subdomain**. You can find your subdomain in the URL of your BambooHR dashboard: `https://your_subdomain.bamboohr.com/home`. Everything before `.bamboohr.com` is your subdomain.
4. Enter the **API key**. To generate it, go to your BambooHR account, click the account icon on the top right, and select **API Keys**. Create a new key and copy it here.
5. Click **Connect**.
6. To connect another account, click **+Add Account** and repeat the steps above. You can add a maximum of 15 accounts.
---
## Accessing BambooHR Functions via Agent Flow
Once integrated, you can drop BambooHR action nodes anywhere in your agent flows.
1. Go to **Automation** and create or open a flow that suits your use case.
2. Navigate to the point in the conversation where you want to add the node. Click **Add Node**, then go to **Integrations** and select **Bamboo HR**.
:::note
When multiple accounts are connected, select the appropriate account for each node. This lets you route different actions through different BambooHR accounts within the same agent.
:::
---
## Action Nodes
### Fetch Employee Information
Fetches the complete profile of an employee — including contact details, department, job title, supervisor, and employment status — using their BambooHR employee ID.
**Required parameters:**
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| Employee ID | Number | The unique numeric ID assigned to the employee in BambooHR. |
**Response includes:** `firstName`, `lastName`, `department`, `hireDate`, `workEmail`, `homeEmail`, `homePhone`, `mobilePhone`, `supervisor`, `location`, `reportsTo`, `employmentStatus`, `jobTitle`, `address1`
> 📖 [BambooHR API Reference — Get Employee](https://documentation.bamboohr.com/reference/get-employee)
---
### Fetch Employee Time-Offs
Fetches all time-off requests submitted by an employee within a specified date range. Returns the request status (approved/denied/requested), type of leave, dates, hours, and any notes from the manager or employee.
**Required parameters:**
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| Employee ID | Number | The unique ID of the employee. |
| Start Date | String (YYYY-MM-DD) | Start of the date range to query. |
| End Date | String (YYYY-MM-DD) | End of the date range to query. |
**Response includes:** `id`, `employeeId`, `name`, `status` (with `lastChanged` and `lastChangedByUserId`), `start`, `end`, `type` (id + name), `amount` (unit + amount), `dates`, `notes`
> 📖 [BambooHR API Reference — Get Time-Off Requests](https://documentation.bamboohr.com/reference/list-time-off-requests)
---
### Apply Time-Offs
Submits a new time-off request on behalf of an employee. This node first fetches the available time-off types from your BambooHR account dynamically and presents them as selectable options, so the agent always reflects your company's current leave policy.
**Required parameters:**
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| Employee ID | String | The unique ID of the employee applying for leave. |
| Timeoff Type | String | The leave type, dynamically fetched from BambooHR (e.g., Vacation, Sick). |
| Start Date | String (YYYY-MM-DD) | First day of the requested leave. |
| End Date | String (YYYY-MM-DD) | Last day of the requested leave. |
| Dates | Array | Per-day breakdown — each entry needs a `ymd` (date) and `amount` (hours). |
| Notes | Array | Notes attached to the request — each entry needs a `from` (`employee` or `manager`) and `note` (text). |
**Optional parameters:** `amount` — total leave in hours across all days.
:::info How the time-off type is fetched
The node calls BambooHR's time-off types API in the background and maps the results to a dropdown in the agent. The `timeOffTypeId` sent in the actual request is resolved automatically from the selected label.
:::
> 📖 [BambooHR API Reference — Add a Time-Off Request](https://documentation.bamboohr.com/reference/create-time-off-request)
---
### Update Time-Offs
Updates the status of an existing time-off request — approve it, deny it, or cancel it — using the request ID. A note can also be attached to explain the decision.
**Required parameters:**
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| Request ID | Number | The ID of the time-off request to update. Obtained from Fetch Employee Time-Offs. |
| Status | String | New status: `approved`, `cancelled`, or `denied`. |
| Note | String | A note explaining the status change (visible to the employee if shared). |
> 📖 [BambooHR API Reference — Change a Request Status](https://documentation.bamboohr.com/reference/update-time-off-request-status)
---
### Update Employee
Updates one or more fields on an existing employee's BambooHR profile. Only pass the fields you want to change — all others remain untouched.
**Required parameters:**
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| Employee ID | Number | The unique ID of the employee to update. |
**Optional parameters:**
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| First Name | String | Employee's first name. |
| Last Name | String | Employee's last name. |
| Department | String | Department name as configured in BambooHR. |
| Hire Date | String (YYYY-MM-DD) | Employee's official hire date. |
| Home Email | String | Personal email address. |
| Work Email | String | Work email address. |
| Work Phone | String | Work phone number. |
| Work Phone Extension | String | Extension for the work phone. |
| Location | String | Office location. |
| Address | String | Street address (address line 1). |
| City | String | City of residence. |
| State | String | State or province. |
| Zipcode | String | Postal/ZIP code. |
| Home Phone | String | Home phone number. |
| Mobile Phone | String | Mobile phone number. |
| Preferred Name | String | Preferred display name. |
| Reports To | String | Employee ID of the direct manager. |
> 📖 [BambooHR API Reference — Update Employee](https://documentation.bamboohr.com/reference/update-employee)
---
### Create Employee
Creates a brand new employee record in BambooHR. Useful for automating onboarding flows where the agent collects employee details and directly provisions the record.
**Required parameters:**
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| First Name | String | Employee's first name. |
| Last Name | String | Employee's last name. |
| Work Email | String | Employee's work email — must be unique in BambooHR. |
**Optional parameters:**
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| Home Email | String | Personal email address. |
| Department | String | Department to assign the employee to. |
| Hire Date | String (YYYY-MM-DD) | Official start date. |
| Location | String | Office or work location. |
| Job Title | String | Employee's job title. |
| Work Phone | String | Work contact number. |
| Mobile Phone | String | Mobile number. |
| Reports To | String | Employee ID of the direct manager. |
**Sample response:** `{ "id": "123", "firstName": "Jordan", "lastName": "Lee", "workEmail": "jordan.lee@example.com", "department": "Engineering", "hireDate": "2024-01-15" }`
> 📖 [BambooHR API Reference — Add Employee](https://documentation.bamboohr.com/reference/create-employee)
---
### Upload Document
Uploads a file to an employee's document folder in BambooHR. Supports any standard file type. You can optionally categorize the document and choose whether the employee can view it in their self-service portal.
**Required parameters:**
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| Employee ID | Number | The unique ID of the employee. |
| File | String | The file content (base64 or binary depending on your flow setup). |
| File Name | String | The actual file name with extension (e.g., `offer_letter.pdf`). |
| Document Name | String | Display name shown in BambooHR (e.g., `Offer Letter - 2024`). |
**Optional parameters:**
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| Category | String | Document category in BambooHR (e.g., `Hiring`, `Performance`). |
| Share With Employee | Boolean | Set to `true` to make the document visible to the employee in their portal. |
> 📖 [BambooHR API Reference — Upload Employee File](https://documentation.bamboohr.com/reference/upload-employee-file)
---
### View Company Benefits
Retrieves all benefit coverage types configured at the company level in BambooHR. No input is needed — this node returns all available coverage options, which you can display to employees or use to drive dynamic benefit selection flows in your agent.
**Response includes:** `id`, `shortName`, `description`, `sortOrder`
Common examples: `Employee`, `Employee + Spouse`, `Employee + Family`, `Employee + Child`, `Employee + Children`, `Two Party`, `Family Only`
> 📖 [BambooHR API Reference — Get Benefit Coverages](https://documentation.bamboohr.com/reference/list-benefit-coverages)
---
### View Employee Benefits
Retrieves the active payroll deductions and benefit enrollment details for a specific employee — including what plans they're enrolled in, how much they pay vs. the company pays, coverage type, and effective dates.
**Required parameters:**
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| Employee ID | Number | The unique ID of the employee. |
**Response includes:** `payFrequency`, and a `deductions` array with: `benefitPlanName`, `employeePays`, `companyPays`, `currencyCode`, `employeePaysType` ($ or %), `companyPaysType`, `coverageType`, `effectiveDate`, `endDate`, `deductionStartDate`, `deductionEndDate`
> 📖 [BambooHR API Reference — Get Employee Payroll Deductions](https://documentation.bamboohr.com/reference/list-employee-benefits)
---
### View Employee Remaining Time-Offs
Fetches the current leave balance for an employee across all time-off policies — accruing (e.g., Vacation, Sick) and discretionary (e.g., FMLA, Bereavement). Ideal for a "check my balance" flow in an employee self-service agent.
**Required parameters:**
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| Employee ID | Number | The unique ID of the employee. |
**Response includes:** `timeOffType`, `name`, `units` (hours or days), `balance`, `end` (balance calculation date), `policyType` (accruing / discretionary), `usedYearToDate`
> 📖 [BambooHR API Reference — Estimate Future Time-Off Balances](https://documentation.bamboohr.com/reference/get-time-off-balance)
---
### View Time-Off Types
Retrieves all time-off types configured in your BambooHR account, along with default working hours per day of the week. No input is needed. Use this before building an Apply Time-Off flow to understand what types are available.
**Response includes:** `timeOffTypes` array (with `id`, `name`, `units`, `color`, `icon`) and `defaultHours` array (hours per day of week)
> 📖 [BambooHR API Reference — Get Time-Off Types](https://documentation.bamboohr.com/reference/list-time-off-types)
---
### View Emergency Contact Details
Fetches all emergency contact records associated with an employee, including their relationship, phone numbers, address, and whether they are the primary contact.
**Required parameters:**
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| Employee ID | String | The unique ID of the employee. |
**Response includes:** `id`, `employeeId`, `name`, `relationship`, `homePhone`, `mobilePhone`, `workPhone`, `workPhoneExtension`, `email`, `addressLine1`, `addressLine2`, `city`, `state`, `country`, `zipcode`, `primaryContact` (`1` = primary)
> 📖 [BambooHR API Reference — Get Employee Table Row](https://documentation.bamboohr.com/reference/get-employee-table-data)
---
### Add Emergency Contact Details
Adds a new emergency contact record for an employee. Only `employeeId` and `name` are required — all other fields are optional but recommended for a complete record.
**Required parameters:**
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| Employee ID | String | The unique ID of the employee. |
| Name | String | Full name of the emergency contact. |
**Optional parameters:**
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| Relationship | String | Relationship to the employee (e.g., Spouse, Parent). |
| Mobile Phone | String | Personal contact number. |
| Home Phone | String | Residential phone number. |
| Work Phone | String | Work phone number. |
| Work Phone Extension | String | Extension for the work phone. |
| Email | String | Email address of the contact. |
| Address Line 1 | String | Street address. |
| Address Line 2 | String | Apartment, suite, etc. |
| City | String | City. |
| State | String | State or province. |
| Country | String | Country. |
| Zipcode | String | Postal/ZIP code. |
| Primary Contact | String | `1` if this is the primary emergency contact, `0` otherwise. |
> 📖 [BambooHR API Reference — Add Employee Table Row](https://documentation.bamboohr.com/reference/create-table-row)
---
### Update Emergency Contact Details
Updates an existing emergency contact record for an employee. You must provide both the `employeeId` and the `rowId` of the specific contact record. Only pass the fields you want to change.
**Required parameters:**
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| Employee ID | String | The unique ID of the employee. |
| Record ID | String | The row ID of the emergency contact entry to update. Obtained from View Emergency Contact Details. |
**Optional parameters:** Same fields as Add Emergency Contact Details. Only the fields you include will be updated.
> 📖 [BambooHR API Reference — Update Employee Table Row](https://documentation.bamboohr.com/reference/update-table-row)
---
### Get Job Info History
Retrieves the full job information history for an employee — every role, department, location, and reporting change recorded in BambooHR. Useful for audits, org chart generation, or display in a manager's dashboard agent.
**Required parameters:**
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| Employee ID | Number | The unique ID of the employee. |
**Response includes:** `id`, `employeeId`, `date` (effective date of the entry), `jobTitle`, `department`, `location`, `division`, `reportsTo`
> 📖 [BambooHR API Reference — Get Employee Table Row](https://documentation.bamboohr.com/reference/get-employee-table-data)
---
### Add Job Info Row
Adds a new entry to an employee's job information history. Use this to record promotions, transfers, reporting changes, or pay updates. The `date` field sets when the change takes effect.
**Required parameters:**
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| Employee ID | Number | The unique ID of the employee. |
| Effective Date | String (YYYY-MM-DD) | The date from which this job info takes effect. |
**Optional parameters:**
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| Job Title | String | New job title. |
| Department | String | New department. |
| Location | String | New work location. |
| Division | String | New division. |
| Reports To | String | Employee ID of the new direct manager. |
| Pay Rate | String | New pay rate. |
| Pay Type | String | Pay type (e.g., Salary, Hourly). |
| Pay Frequency | String | Pay frequency (e.g., Monthly, Bi-weekly). |
> 📖 [BambooHR API Reference — Add Employee Table Row](https://documentation.bamboohr.com/reference/create-table-row)
---
### Get Who's Out
Returns a list of all employees who have approved time-off falling within the specified date range. Useful for building a "who's out today/this week" command in a manager or team lead agent.
**Required parameters:**
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| Start Date | String (YYYY-MM-DD) | Start of the date range to check. |
| End Date | String (YYYY-MM-DD) | End of the date range to check. |
**Response includes:** `id`, `employeeId`, `name`, `start`, `end`
> 📖 [BambooHR API Reference — Get Who's Out](https://documentation.bamboohr.com/reference/list-whos-out)
---
### Terminate Employee
Records an employee termination in BambooHR by adding a new entry to their employment status history. The `employmentStatus` is automatically set to `Terminated` — you only need to provide the date and any optional context.
**Required parameters:**
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| Employee ID | Number | The unique ID of the employee to terminate. |
| Termination Date | String (YYYY-MM-DD) | The effective date of the termination. |
**Optional parameters:**
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| Comment | String | Internal note or reason for termination. |
| Termination Type ID | String | ID for the type of termination (voluntary/involuntary). Get valid IDs from your BambooHR account metadata. |
| Termination Reason ID | String | ID for the reason code. Get valid IDs from your BambooHR account metadata. |
| Eligible For Rehire ID | String | ID indicating rehire eligibility. Get valid IDs from your BambooHR account metadata. |
:::note
The `employmentStatus` field is automatically set to `Terminated` by the node and does not need to be passed manually. This action is irreversible through the agent — ensure the flow includes a confirmation step before executing.
:::
> 📖 [BambooHR API Reference — Add Employment Status Row](https://documentation.bamboohr.com/reference/create-table-row)
---
### Fetch Employee Employment Status
Retrieves the full employment status history for an employee, including all past changes such as active, terminated, or rehired. Each entry includes the effective date, status value, and any comment attached.
**Required parameters:**
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| Employee ID | String | The unique ID of the employee. |
**Response includes:** `id`, `employeeId`, `date`, `employmentStatus`, `comment`
> 📖 [BambooHR API Reference — Get Employee Table Row](https://documentation.bamboohr.com/reference/get-employee-table-data)
---
### Get Custom Fields Schema
Fetches the complete list of all custom employee fields defined in your BambooHR account — both standard and company-defined. Use this node to dynamically discover what fields are available before building update or fetch flows, rather than hardcoding field names.
No input parameters required.
**Response includes:** `id`, `name`, `type` (e.g., text, list, date)
> 📖 [BambooHR API Reference — Get a List of Fields](https://documentation.bamboohr.com/reference/list-fields)
---
## Error Reference
All BambooHR action nodes return structured errors. The following codes may appear in the agent's error path:
| Error Status | Code | HTTP Status | What it means | How to fix |
| ------------ | ---- | ----------- | ------------- | ---------- |
| `DOMAIN_OR_EMPLOYEE_NTFND` | 8000 | 404 | The subdomain or employee ID doesn't exist in BambooHR. | Verify the subdomain in your integration config and confirm the employee ID is valid. |
| `INVALID_ARGUMENT` | 8001 | 400 | One or more parameters are missing, wrong type, or incorrectly formatted. | Check that all required fields are present and dates follow the `YYYY-MM-DD` format. |
| `UNAUTHORISED` | 8002 | 403 | The API key doesn't have permission to perform this action. | Check the API key's permission scope in BambooHR under **Admin** > **API Keys**. |
| `INVALID_VALUE` | 8003 | 409 | A field value conflicts with existing data or fails BambooHR validation. | Verify enum values, duplicate email checks, or conflicting dates. |
| `AUTHENTICATION_ERROR` | 9000 | 401 | The API key is invalid or has been revoked. | Regenerate the API key in BambooHR and update it in your Yellow.ai integration config. |
---
## Related Resources
- [BambooHR API Documentation](https://documentation.bamboohr.com/reference)
- [Yellow.ai Integration Setup Guide](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/bamboohr)
- [BambooHR — Managing API Keys](https://www.bamboohr.com/product-updates/admin-api-keys-settings)
- [BambooHR — Time-Off Overview](https://documentation.bamboohr.com/reference/list-time-off-requests)
- [BambooHR — Employee Table Rows Reference](https://documentation.bamboohr.com/reference/get-employee-table-data)
---
## BillDesk EmailPay
The [BillDesk EmailPay](https://www.billdesk.com/web/) integration enables your AI agent to manage the following BillDesk functions.
1. Generate a payment link to receive payments
2. Check the status of the payments and recieve notifications on the same.
## 1. Integrate BillDesk EmailPay with Yellow.ai
To connect your BillDesk account with yellow.ai, follow these steps:
### 1.1 Connect BillDesk EmailPayto Yellow.ai
In a two-tier environment, you can connect an integration app in the Development environment. In a three-tier environment, you can connect the integration app either in Staging or Sandbox. All connected integrations are available in the live environment.
1. Navigate to the Development/Staging environment and go to **Extensions** > **Integrations** > **Payment** > **BillDesk EmailPay**. You can also use the Search box to easily find the required integration.
2. In **Give account name**, enter a unique name for the integration. You can use only lowercase alphanumeric characters and underscores (_).
3. Enter these details from BillDesk - **Key ID**, **Client ID**, **Merchant ID**, **BillDesk public key CDN URL**, and **API base URL**.
4. Click **Connect**.
5. If you have multiple accounts, click **+ Add account** and follow the above mentioned steps to add each of them. You can add a maximum of 15 accounts.
### 1.2 Configure webhook URL in Billdesk dashboard
1. Copy the webhook URL mentioned in the **Instructions to connect** section of the **Billdesk EmailPay Integration Card**.
2. Append the region of your AI agent to the domain of the webhook url. r1/r2/r3/r4/r5 are the regions of your AI agent, you can refer the following list for the same.
* r1 - MEA
* r2 - Jakarta
* r4 - USA
* r5 - Europe
* r3 - Singapore
For example, if the domain is https://cloud.yellow.ai, you need to change it to https://r1.cloud.yellow.ai if the region of the AI agent is MEA. If the AI agent belongs to India, you can use origin domain itself.
3. Share the webhook URL to **BillDesk SPOC**. They will configure the webhook at their end.
### 1.3 Define the fields to be passed in the API
Please specify the **Min length**, **Max length** and the **data type**(numeric/alphanumeric) for the UDFs that are mentioned in this table.
| params | data_type | Min Length |Max Length |UDF Field mapped to BillDesk|
| -------- | -------- | -------- |-----|--|
| amount | numeric | 1 |10000000|UDF 1|
|phone_num|alphanumeric|1|10| UDF 2|
|name|alphanumeric| 1|50|UDF 3|
|sender|alphanumeric|1|50|UDF 4|
|source|alphanumeric|1|25|UDF 5|
|unique_ID|alphanumeric|1|50|UDF 6|
|order_ID|alphanumeric|1|25| UDF 7|
### 1.4 Receive events in Yellow.ai
To receive events and trigger flows based on events, you need to enable that specific event in your AI agent settings.
1. In the Development/Staging environment, go to **Automation** > **Event**.
2. In **Integrations** > **Billdesk EmailPay Payment Status**.
3. Click on the three dots icon and click **Activate**.
4. You can trigger a flow based on this event or perform a specific action (for example, display an appropriate message to the end user).
:::info
If you have added multiple accounts in your platform, you need to enable events for each account.
:::
## 2. Generate Payment Link through AI agent conversation
You can generate payment links for your customers to pay.
:::note
When multiple accounts are added, select the appropriate account for each node, allowing you to leverage the unique functionalities of each account for their intended purposes.
:::
1. In the Automation flow builder, select the **Integrations** node and click **Billdesk EmailPay** from the list of integrations that have been enabled for that AI agent.
2. After clicking **Billdesk EmailPay**, an **Integration Action Node** will be added to the flow builder. Click that node and select **Generate Payment Link** from them.
3. Fill in all the mandatory fields. The below-mentioned table consists of the sample value, data type and description for all these fields.
| Field Name | Sample Value | Data type |Description|
| -------- | -------- | -------- |--|
| Amount | 100 | String | Amount to be paid using the Payment Link. Only two digit after decimal is supported.|
|Customer Phone Number|INR|String|Customer phone number.|
|Customer Name|Test|String|Name of the customer.|
|Order ID|TestOrder122|String|Unique Order ID.|
|Send Email|false|Boolean|Sending link through email**True:** Payment link will be sent via email (Currently not supported).**False:** Payment link will be generated in the AI agent.
4. The **Generate Payment Link** Integration Action Node has two outcomes, success or failure. If the payment link is generated successfully, the **Integration Action Node** returns a **Success** response code as shown below.
```json
{
"url": "https://uat.billdesk.com/MercOnline/URLRenderer/C7g",
"status": "success"
}
```
If generating payment link fails, the **Integration Action Node** returns a **Failure** response code as shown below.
```json
{
"errorCode": "<>"
"errorMessage": "<>"
"status": "failed"
}
```
To use this **Integration Action Node** in an app.yellow.ai AI agent, refer the following example:
```
app.executeIntegrationAction({
"integrationName": "billdesk-emailpay",
"action": "Generate payment link",
"dynamicParams": {
"amount": 10.00,
"customerName": "John",
"customerMobileNumber": "9955557879",
"orderId": "TestOrder123",
"sendEmail": "false"
}
}).then((res) => {
console.log("response from action node", res);
app.log(res, '||Response from action node||')
}).catch((err) => {
console.log("Error in action node", err);
app.log(err, '||Error in action node||')
})
```
---
## Billdesk UPI integration
Yellow.ai Integration with Billdesk UPI Payment Gateway allows you to create UPI Intent for WA Pay, view payment status and Send UPI notification with the yellow.ai platform.
## Connecting BillDesk to yellow.ai
You can connect your account only in development environment and not in live. For a three-tier environment, you can connect an account in Staging and Sandbox environment. Once the AI agent is published, it will use the integrations if they are configured in the flows.
1. Get the KeyId, Client Id, Merchant Id, Public Key File and API Base URL from Billdesk Team.
2. Upload your Public Key file in some bucket or server like (AWS-S3, SFTP, etc) and Get the public CDN Url . Note:(CDN URL should be public readable).
3. On the [Cloud platform](https://cloud.yellow.ai), navigate to the Development/Staging environment and click **Extensions** > **Integrations** > **Payment** > **BillDesk**. You can also search for the Cashfree app.
4. In **Give account name**, enter a unique name for the integration. You can use only lowercase alphanumeric characters and underscores (_).
5. Enter **Key ID**, **Client ID**, **Merchant ID**, **BillDesk public key CDN URL**, **API base URL** and click **Connect**.
6. To connect multiple accounts, click **+ Add account** and follow the instructions mentioned above. You can connect upto 15 accounts per integration.
### Events to enable for BillDesk UPI Payment
You need to Activate the **Billdesk Payment Status** after integrating BillDesk.
To know how to enable events, refer to [this doc](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/overview#step-4-enable-integration-events-in-your-bot).
## BillDesk actions from AI agent conversations
Once the Stripe account is connected, you can perform the following actions through AI agent conversations: Generate UPI intent and Generate UPI collect.
1. Go to Development/Staging environment and navigate to Automation > Build > Select the flow where you want to add the Generate payment link node.
2. Click **Add node** > **Integrations** > **BillDesk**.
3. In **Action**, choose your preferred action.
### 1. Generate UPI Intent
Generate UPI collect BillDesk refers to a process where you create a request to collect funds from the user using UPI through the AI agent conversation.
Get the final amount from your cart total and call the Generate UPI Intent action node of integration, get the transaction Id and Intent URI for whatsapp pay api.
_ Node Input Params:-_
|Field Name|Sample Input|Description|
|--- |--- |--- |
|Amount*|200|The amount for the request.|
|Additional Parameters|any varchar|additional_info values that can be attached to the transaction.|
|Additional Parameters|John@test.com|additional_info values that can be attached to the transaction.|
|Additional Parameters|Some value|additional_info values that can be attached to the transaction.|
:::note
To use in the [App platform](https://app.yellow.ai) AI agent use below function.
:::
```json
app.executeIntegrationAction({
"integrationName": "billdesk",
"action": "Generate UPI Intent",
"dynamicParams": {
"amount": 100
}
}).then((res)=>{
console.log("response from action node", res);
app.log(res, '||Response from action node||')
}).catch((err)=>{
console.log("Error in action node",err);
app.log(err, '||Error in action node||')
})
```
##### Sample Success Response:
```json
{
"objectid": "transaction",
"transactionid": "X7890477676443",
"orderid": "UPIODR00000004",
"mercid": "BDMERCID",
"transaction_date": "2022-03- 18T11:50:27+05:30",
"amount": "2.00",
"surcharge": "0.00",
"txn_process_type": "collect",
"bankid": "789",
"itemcode": "DIRECT",
"auth_status": "0002",
"transaction_error_code": "TRP0000",
"transaction_error_desc": "Transaction Pending",
"transaction_error_type": "pending",
"payment_method_type": "upi"
```
### 2. Generate UPI Collect
The end customer will authorize the transaction via the UPI PSP mobile app. On successful authorisation, BillDesk will receive a callback from the acquirer, and in turn BillDesk will notify the merchant via webhook notification.
_ Node Input Params:-_
|Field Name|Sample Input|Description|
|--- |--- |--- |
|Amount*|200|The amount for the request.|
|VPA*|billdesk@upi|UPI Id of customer|
|Additional Parameters|any varchar|additional_info values that can be attached to the transaction.|
|Additional Parameters|John@test.com|additional_info values that can be attached to the transaction.|
|Additional Parameters|Some value|additional_info values that can be attached to the transaction.|
:::note
To use in the [App platform](https://app.yellow.ai) AI agent use the below function.
:::
```json
app.executeIntegrationAction({
"integrationName": "billdesk",
"action": "Generate UPI Collect",
"dynamicParams": {
"amount": 100,
"vpa":"billdesk@upi",
"additionalParameters4":"anything"
"additionalParameters5":"anything"
"additionalParameters6":"anything"
}
}).then((res)=>{
console.log("response from action node", res);
app.log(res, '||Response from action node||')
}).catch((err)=>{
console.log("Error in action node",err);
app.log(err, '||Error in action node||')
})
```
##### Sample Success Response:
```json
{
"objectid": "transaction",
"transactionid": "X7890477676443",
"orderid": "UPIODR00000004",
"mercid": "BDMERCID",
"transaction_date": "2022-03- 18T11:50:27+05:30",
"amount": "2.00",
"surcharge": "0.00",
"txn_process_type": "collect",
"bankid": "789",
"itemcode": "DIRECT",
"auth_status": "0002",
"transaction_error_code": "TRP0000",
"transaction_error_desc": "Transaction Pending",
"transaction_error_type": "pending",
"payment_method_type": "upi"
```
---
## Camspay payment integration
Yellow.ai Integration with Camspay Payment Gateway allows you to generate payment links and view payment status with the Yellow.ai platform.
## 1. Connect Camspay payment with Yellow.ai
Before starting the integration process, from your Camspay dashboard, obtain the merchant ID, sub-biller ID, API key, and encryption-decryption key from the Camspay team.
:::note
In a two-tier environment, you can connect an integration app in the Development environment. In a three-tier environment, you can connect the integration app either in Staging or Sandbox. All connected integrations are available in the live environment.
:::
1. On the [cloud platform](https://cloud.yellow.ai), navigate to the Development/Staging environment and click **Extensions** > **Integrations** > **Payment** > **Camspay**. You can also search for the Camspay Payment using the Search box.
2. In **Give account name**, enter a unique name for the integration. You can use only lowercase alphanumeric characters and underscores (_).
3. Enter your Camspay Payment account's **Merchant ID**, **Subbiller ID**, **API key**, **Encryption-Decryption key**, and the **API Base URL** captured from the Camspay.
4. Click **Connect**.
5. To connect more accounts, click **+ Add account** and follow the above mentioned steps to connect each account.
:::note
You can add a maximum of **15 merchant accounts**.
:::
## 2. Configure webhook URL
The webhook URL serves as a callback endpoint where Camspay can send notifications or updates regarding the payment related events.
:::info
Click [here](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/overview#step-3-configure-webhook-url) to learn how to configure Webhook URL in your app.
:::
## 3. Enable integration event in your AI agent
Open **Automation > Events > Integrations > Camspay payment status** and select **Activate** by clicking the menu next to it.
**Camspay Payment Status** event allows you to execute specific actions in response to events. For example:
- Display a message in the AI agent conversation when a payment is successful.
- Show order details in the AI agent conversation when an order is placed.
Event | Description
----- | -----------
Camspay Payment Status | Returns payment/refund status
:::info
Click [here](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/overview#step-4-enable-integration-events-in-your-bot) to learn about enabling integration events.
:::
## 4. Trigger AI agent flows with integration events
In the start node of a flow, select **Trigger type** as **Event** and select **Camspay payment status** next to it.
:::info
Click [here](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/overview#step-5-trigger-bot-flows-with-integration-events) to learn how to trigger flows with events.
:::
## 5. Generate Camspay payment links in AI agent conversation
Once your Camspay account is successfully connected, configure the node, follow:
1. Go to Development/Staging environment and navigate to **Automation** > **Build** > Select the flow where you want to add the Generate payment link node.
2. Click **Add node** > **Integrations** > **Camspay**.
3. Choose the **Action**, **Create payment request** and configure the input fields.
Details within the selected action:
| **Field Name** | **Data Type** | **Description** |
|-----------------------------|---------------|-------------------------------------------------|
| Amount | string | Payment amount |
| Customer Email | string | Email address of the customer |
| Customer Mobile | string | Mobile number of the customer |
| Customer Name | string | Full name of the customer |
| Failure redirect URL | string | URL to redirect to after failed payment |
| Remarks | string | Additional comments or notes. Ex: Purpose of the payment |
| Success redirect URL | string | URL to redirect to after successful payment |
| Transaction ID | string | Unique transaction identifier generated for each payment |
| Device type | string | Device type used for the transaction. Ex: Web or Mobile |
| Intent call | string | Selecting Y/N will open payment links based on the device. Select Y(yes) for a WhatsApp AI agent, to open the UPI link in the apps available on the phone. Select N(no) for a Web AI agent, to open payment link in a new browser tab. |
| Pay type | string | Primary payment type. Example: UPI, Net Banking(NB), Credit card(CC), Debit card(DC) and all the mentioned types |
| Sub pay type | string | Secondary payment method or subtype. Example: UPI, Net Banking(NB), Credit card(CC), Debit card(DC) and all the mentioned types |
| User defined field 1 | string | Custom field for additional data (1) |
| User defined field 2 | string | Custom field for additional data (2) |
| User defined field 3 | string | Custom field for additional data (3) |
| User defined field 4 | string | Custom field for additional data (4) |
| User defined field 5 | string | Custom field for additional data (5) |
| User defined field 6 | string | Custom field for additional data (6) |
| User defined field 7 | string | Custom field for additional data (7) |
| User defined field 8 | string | Custom field for additional data (8) |
| User defined field 9 | string | Custom field for additional data (9) |
| User defined field 10 | string | Custom field for additional data (10) |
| VPA | string | Virtual Payment Address (for UPI transactions) |
:::note
**Generate payment link** is deprecated. We highly recommend you to use only **Create payment request** action.
:::
---
## Cashfree Payment Gateway integration
Yellow.ai Integration with Cashfree Payment Gateway allows you to generateTransaction ID and view payment status with the yellow.ai platform.
## Connecting Cashfree with Yellow.ai
1. Login to your Cashfree dashboard and copy the App ID and Secret.
2. On the [Cloud platform](https://cloud.yellow.ai), navigate to the Development/Staging environment and click **Extensions** > **Integrations** > **Payment** > **Cashfree**. You can also search for the Cashfree app.
3. In **Give account name**, enter a unique name for the integration. You can use only lowercase alphanumeric characters and underscores (_).
4. Paste the **App Id** and **Secret key**.
4. Choose the API base URL according to the type of Cashfree account that has been configured.
5. To connect more accounts, click **+ Add account** and follow the above mentioned steps to connect each account. You can add a maximum of 15 merchant accounts.
## Enable Cashfree related events for the AI agent
The `Cashfree payment status` event Indicates an update in the payment status. Each payment undergoes different status such as Pending, Processing, Completed, Failed, Refunded, or Cancelled.
:::note
* Activate the Cashfree Payment Status after configuring cashfree credentials at the integration page.
* If you have added multiple accounts in your platform, enable events for each of those accounts.
:::
## Manage Cashfree actions through AI agent conversation
This integration enables the AI agent to perform the following Cashfree actions:
* Generate transaction ID
:::note
When multiple accounts are added, select the appropriate account for each node, allowing you to leverage the unique functionalities of each account for their intended purposes.
:::
### Generate Transaction ID
This action sends a POST request for creating a new transaction and generates the transaction ID.
1. In the Automation flow builder, select the **Integrations** node and click **Cashfree** from the list of integrations that have been enabled for that AI agent.
2. After clicking **Cashfree**, an **Integration Action Node** will be added to the flow builder. When you click that node, you will see all use-cases of this integration in a drop-down. Choose **Generate Transaction ID**.
3. Fill in all the mandatory fields. The below-mentioned table consists of the sample value, data type and description for all these fields.
**Node Input Params**
| Field Name | Description |Sample Input |
| -------- | -------- | -------- |
| Order ID | The unique identification for the order to be created | Order1234 |
|Order Amount | The amount for the request. The minimum amount is 1 |200|
| Order Currency | The currency in which the order with the amount specified has to be created | INR |
|Customer ID|The unique Identification for the Payer|9999999999|
|Customer Email| Email of the payer | john@test.com |
| Order Tags | Tags that are to be attached with the order | `{‘comment’: ‘note to be appended’}` |
|Notify Url|Copy Webhook URL from cashfree card at integration page|Ex: `https://dummyurl.yellowmessenger.com/integrations/genericIntegration/cashfree/x1674?id=C1f1Z1htZNZ%2BFYF6c76riwNWY%3D`)|
**Sample Success Response**
```json
{
"cf_order_id": 2678043,
"order_id": "order_1742302CCpwK00k2bp00fwIwblCVtyPqV",
"entity": "order",
"order_currency": "INR",
"order_amount": 1.00,
"order_expiry_time": "2022-08-19T17:00:57+05:30",
"customer_details": {
"customer_id": "123e344",
"customer_name": null,
"customer_email": "abc@gmail.com",
"customer_phone": "1234567890"
},
"order_meta": {
"return_url": null,
"notify_url": null,
"payment_methods": null
},
"settlements": {
"url": "https://sandbox.cashfree.com/pg/orders/order_1742302CCpwK00k2bp00fwIwblCVtyPqV/settlements"
},
"payments": {
"url": "https://sandbox.cashfree.com/pg/orders/order_1742302CCpwK00k2bp00fwIwblCVtyPqV/payments"
},
"refunds": {
"url": "https://sandbox.cashfree.com/pg/orders/order_1742302CCpwK00k2bp00fwIwblCVtyPqV/refunds"
},
"order_status": "ACTIVE",
"order_token": "WKQXlA9jzfUIytw6adbA",
"order_note": null,
"payment_link": "https://payments-test.cashfree.com/order/#WKQXlA9jzfUIytw6adbA",
"order_tags": null,
"order_splits": []
}
```
----
### Create order
This option is used to create orders with Cashfree.
1. In the Automation flow builder, select the **Integrations** node and click **Cashfree** from the list of integrations that have been enabled for that AI agent.
2. After clicking **Cashfree**, an **Integration Action Node** will be added to the flow builder. When you click that node, you will see all use-cases of this integration in a drop-down. Choose **Create order**.
3. Fill in all the mandatory fields. The below-mentioned table consists of the sample value, data type and description for all these fields.
| Field name | Sample value| Data type |Description |
| -------- | -------- | -------- |----|
Customer details | `{"customer_name":"variables.CashfreeName","customer_phone":"variables.phoneno","customer_email":"variables.email","customer_id":"variables.ID"}` | Object | Customer details including name, email, and phone number.
Order amount | 200 | String | The amount for the request. The minimum amount is 1
Order currency | INR | String | The currency in which the order with the amount specified has to be created
Order tags | `{‘comment’: ‘note to be appended’}` | Object | Custom Tags in thr form of `{"key":"value"}` which can be passed for an order.
Order ID | Order1234 | String | The unique identification for the order to be created
Order Split | `[{ "amount": 10, "vendor": "john" }]` | Array | If you have Easy split enabled in your Cashfree account then you can use this option to split the order amount.
**Sample Success Response**
```json
{
"cf_order_id": 4751313578,
"created_at": "2025-10-08T15:26:05+05:30",
"customer_details": {
"customer_id": "24",
"customer_name": "Dwij",
"customer_email": "dwij.test@gmail.com",
"customer_phone": "9865731549",
"customer_uid": null
},
"entity": "order",
"order_amount": 100,
"order_currency": "INR",
"order_expiry_time": "2025-11-07T15:26:05+05:30",
"order_id": "order_12567533mLacG69H3JGeses26XifrGaGg",
"order_meta": {
"return_url": null,
"notify_url": null,
"payment_methods": null
},
"order_note": null,
"order_splits": [],
"order_status": "ACTIVE",
"order_tags": {
"product": "car",
"~|||~sender": "1410079569550798091459993047363",
"~|||~source": "yellowmessenger",
"~|||~uniqueId": "85cc4ba7-aabf-4f14-82c7-df0b8d33227e"
},
"payment_session_id": "session_9fNT0flnHnqtzZgcDMR6lYuuAjxyuJEzZKBkLWQtZU30uOo6C0tgtq8S58ZSAL8ZtdBvEXYHE7MwseGrvl3Hkxc0nlHhQuM9w0F0ZpBMxFH8nWxR4YJEaA_79B0payment",
"payments": {
"url": "api.cashfree.com/pg/orders/order_12567533mLacG69H3JGeses26XifrGaGg/payments"
},
"refunds": {
"url": "api.cashfree.com/pg/orders/order_12567533mLacG69H3JGeses26XifrGaGg/refunds"
},
"settlements": {
"url": "api.cashfree.com/pg/orders/order_12567533mLacG69H3JGeses26XifrGaGg/settlements"
},
"terminal_data": null
}
```
A sample screenshot of create order:
----
-----
### Order pay
1. In the Automation flow builder, select the **Integrations** node and click **Cashfree** from the list of integrations that have been enabled for that AI agent.
2. After clicking **Cashfree**, an **Integration Action Node** will be added to the flow builder. When you click that node, you will see all use-cases of this integration in a drop-down. Choose **Order pay**.
3. Fill in all the mandatory fields. The below-mentioned table consists of the sample value, data type and description for all these fields.
| Field name | Sample value| Data type |Description |
| -------- | -------- | -------- |----|
Payment session ID | session__CvcEmNKDkmERQrxnx39ibhJ3Ii034pjc8ZVxf3qcgEXCWlgDDlHRgz2XYZCqpajDQSXMMtCusPgOIxYP2LZx0-05p39gC2Vgmq1RAj--gcn | String | Generates a payment session ID.
Payment method | `{"card":{"channel":"link","card_number":"4111111111111111","card_holder_name":"Tushar Gupta","card_expiry_mm":"06","card_expiry_yy":"22","card_cvv":"900"}}` | Object | Make payment using either plain card number, saved card instrument id or using cryptogram.
**Sample Success Response**
```json
{
"action": "custom",
"cf_payment_id": 4428254730,
"channel": "qrcode",
"data": {
"url": null,
"payload": {
"qrcode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAIAAAACACAIAAABMXPacAAAJyElEQVR4nOydS6wVSRmAq6r7vIDDhbsg1wS5PJRwCZoQ40YToySy0AUmPlZGDIlrVxrFB0YkIUZXblwYE0JiiI+FwUjE4AIWRueRYRZ3AhMCMxOYCTMD3Hvncs+r+5909zl9Ll1dVX9VNak+mfowDulTr1N//3//j+pDSCwAgOwvlNLClZz8I1EX/iMRfBdJ36yxZIUGC+BXIhkNCTPr5qkKLwDHTBUHr4C8gheub0appJh58dMVhjWwWpgGSouHIeviNcAxXgCOKfGCtNRW1CAfxNg90JqXx8AmFKaTGBzk7JLBc7wGOMYLwDFWgVgORlsLH0lslCh6kswimhdjCkRRleS72FinAl4DHOMF4JhqTFCOROULeq0VVSlbiuyYZBbMILoLM8BrgGO8ABxTYoJsnuxKzwGjzspkL8Y/EXkymL74LiLwXbwGOMYLwDFTE1Tts14UqmBKVMpATDmLJHbTuoLvUtoRg9cAx1D7YNosncCjrNZiEgDKexBf/9HqYozXAMd4ATgm1NJrfIFXOSxGrw1ynHgMBrE5jSJKingNcIwXgGP0asI5Boc+ROA9KC0HBl/DsSnI2JCN7zXAMV4AjqFaB2yV6Uml84M/xsuD8T3wjpPBKV2Dk3HKpXoNcIwXgGNQT3MDCyMZRNkFn3TUOv6PbIDB4FUG0VK9BjjGC8Axspow/gQHf9hEGd0Y5FUMjrlpzaIMxPD7IKEwi9cAx4Ra1Qb7CpzW+U7lbWsQVdhUIvF98W/XeA1wjBeAY0pSETmVZAsqjBj4vvgX7fD5Bpsyi8EsXgMc4wXgmNDssKb8emmbAjYBAd7HkHTBg7erPMqsidcAx3gBOKYkEMPXLgwib0yDSk7V4c+GKsfEgC8j+0CsXpScDTXwskvGNQ3WAWD51bu//cWfblx7ZdAfan6dclrt5hePf+b7P/3W4U/vwzsOBjtjoAHTTdHyZPABiK4Zub385jeOnV570gMyErU0gJKwO9f+87Vzh44sFj9CJ25Fay6ZDm0ta2eCfv3zi2tPekFY8YHkIIS1ld75n1yodlh7aqcBB+e+OeiPCClZTHYpMZo6WdjNTZvNxu3VvxQbONWA0KBSofUw0I2MBv0hEKBcsRqSrYTkD0v+SyOcirDxWiGZkQwGQ8nXtAkAlYj2ueIXtSuB3/3sRgaghBHaB0JJ3EV9c9onJE40hibf/Dms1Zo6CoAHxioAtEeGHw9Wvrul/4mQjPe0bF8BgBHWg10/WAnWAMJa7n0K6j1hZS7IOH/Lj7bYOsF3otmfEUS7gvd+3B3uC9g6EEpF1o0QGs2zrVd6wWpc2H2buE9ZIzNIcNVcA9JbP7EgwMLE+Kx+vjnYH4SPYmhQEhLGOBEAieNEBJ0b/Z1/XE+1pp62Z4zsDRnlIQAtkI7T3vbX8gupy5Pscm/A1vvBdjKEHYzGNG7R5t1oy1831nvB5v3NHtRz3Sh8HLeWR8kTu0EpKEQg+pqSDVHWqPkrs/QQnpA4nIyS9R7bu9D7+rGH16/vuDbYxgiQBo0ewtJrqye/+jalyf2e/T+jsNEPfve33RsQkCZJNWdsqWqrBHUWADAKTwfB0U+uXfjZ8sKBpw/uLP1zyEKaOKNDwnbtGX7v1H3CgMSp3xQRMje89fLO85cX2cR4gfAxXRcYTKATJK1BAN9AdEUyC389AtoI4jOn7i0s9KJHjcGQsTQMS294AhEhfTr+Xy9xU1fe6pz+/f7eIAgo0GxAi92vdkP40bLrtdaAKGJz20ZLi+vxRsCawFJjw1JrEwSw8kH4nxfmaSoSIOSdR82LVz724uvbuq1RHCs2rj7UWQA08WCSGxEyjz9/mCZOTiO+c7/znbNLk4t0Y8QCAt12NNn9Olv+KaiaMI/x6UnNaZIZMjeUwHQ7x9tLSMDyrAVsb48IIenuE8nu40s0vM8jcerxGewZ8oLGqx0/RzdFXZBtME1lMklcTEVFav7cfYaaC6Acmj6I0zDhmRRP7V2eEqzeE8ZgcIJDPFZ2m6d/ZWmGgmlbeqUZ4VtqDau8PrM14SxJnXg8ELdZ496IRUDYrN3wHLMigNToxAAdGs2z9kuD7uWNOKBEqzRTS2THUpR1GAn4Y26IoRIPiMYQN2n75nDrb/qdK33WI9CgWaxblQwMTtoaTD5bXtDY26GZEDqk/b/B3M3hqMGyLFtNiyw61NoEpWY/ucnj9En74N1WQGHUYcCy+FdQD5gpZL+aiD/jj6kJ40/O5F0JMCA0DCCYH/zr6sL/b23fEsYkIpRUaXnEC5isA/E2lciDktRwMupsgjJfHx6vhv/47+4zfziQWKEgszuzb3omoL6I8nQbPnRQ1n82lSSzJyx0WvH7q41mGDcCiMH2qf5G/++lC9M6NoqvOCp9nDpqwCS2YonrA3TtabC1FQEhMSjyPKphS067OKd2D+FmszHZJEhlAGFidvI8j3mOkxLWbDWqXGsVML6GwCMqJoiuSwoyfIPCIJ/70qcoCcMwyJqTLN82Vlzz+koYBpQEX/jyUUkbvnhS+Hb5FVGZBbOZhdFqpwE/OneyO9eORhXbimhEuzvaP/zlt6sd1p7aCeDQkcVL//7V8ROfbVVnLprNxrGvHL109ezBw3uqGrMqZO8HKMEfcsK/HyAfX3cWzJpFHxkc9pc0EC2sdhrwUcMLwDF6v5qYo4yqRH0N3nzj+9pYHvx0kr74kE05uNcAx3gBOGaaitBK7Chf4hFlEA2slhbKogrGfCmPp4tGM/AGvQY4xgvAMc+kccaXEAERXuOEE+trq3I9/Pg2zg8/Hb4v3pP0GuAYLwDHWOWCcgxCFYzjJMLgwIhZvKm7MAmieb0GOMbqITwdBe3dayVBlX3xg+Ddf0mUU621yPp6DXCMF4BjSs6GGrzmIcEmr1Doq3Vu3j6fgUljKDMfyoV5DXCMF4BjDP9FbYNUhEivlbNIUC5Aq3JSaGxT8ea/gqiL1wDHeAE4Ru/XUkQfPe83Z5SN8Q3wJ+krWZgSrwGO8QJwjOwf8cF/pHR++ASLTcRkUyGRODDKTBd+JfgiudcAx3gBOMbw11IybCoVGFNQmAiTnOE/Ui7AYIWixgbhntcAx5QczMKgLPgpqTbQF32EP/IuQSsLK+or8j68BjjGC8Axer8XZP9CiGTMam2CKFkiCUQK3w4TbfhUxMzjBeCYat6Ux3hQ+Khd+RH+9TmDuq7Ex5OsRHnoRjSv1wDHeAE4puIf6zAIfPD2BNNA1BKfTpBg4Kcp5/Ua4BgvAMeg/g0ZA/Cm4DnFXza2SHdMzCkYUV+vAY7xAnCM4cm4ApjCiPIwHY+BGTEo0iqXZLNU5bxeAxzzYQAAAP//MyuEtbpQVu4AAAAASUVORK5CYII="
},
"content_type": null,
"method": null
},
"payment_amount": 100,
"payment_method": "upi"
}
```
A sample screenshot of Order pay:
---
### Payment link generation
1. In the Automation flow builder, select the **Integrations** node and click **Cashfree** from the list of integrations that have been enabled for that AI agent.
2. After clicking **Cashfree**, an **Integration Action Node** will be added to the flow builder. When you click that node, you will see all use cases of this integration in a drop-down. Choose **Payment link generation**.
3. Fill in all the mandatory fields. The below-mentioned table consists of the sample value, data type and description for all these fields.
| Field name | Sample value| Data type |Description |
| -------- | -------- | -------- |----|
Customer information | `{"customer_name": "John Doe","customer_phone": "9999999999","customer_email": "john@cashfree.com","customer_bank_account_number": 11111111111,"customer_bank_ifsc": "SBIN0001882","customer_bank_code": 7001}` | Object | Customer details including name, email, and phone number.
Amount | 100 | Number | The amount that should be the payment link. This must be in the smallest unit of the currency. For example, if you want to receive a payment of ₹299.95, you must enter the value 29995.
Currency | INR | String | Default is INR, we also accept payments in [international currencies](https://razorpay.com/docs/payments/international-payments/#supported-currencies).
Options | Reference details | Object | Custom options
Notes |`{"key_1": "value_1","key_2": "value_2"}` | Object | Key-value pair that can be used to store additional information about the entity. Maximum 5 key-value pairs.
Link description | Payment for PlayStation 11 | String | A brief description for which payment should be collected.
Enable auto reminder | true or false | Boolean | If "true", reminders will be sent to users for collecting payments.
Link expiry time in ISO | 1 min | String | The timestamp after which the payment link will expire.
Notification options | `{ "email": true, "sms": true }` | Object | Defines how payment link notifications will be sent (via email, SMS, or both).
**Sample success response**
```json
{
"cf_link_id": 126598642,
"customer_details": {
"customer_name": "John",
"country_code": "+91",
"customer_phone": "9865731549",
"customer_email": "John.test@gmail.com"
},
"enable_invoice": false,
"entity": "link",
"link_amount": 100,
"link_amount_paid": 0,
"link_auto_reminders": false,
"link_created_at": "2025-10-09T13:03:44+05:30",
"link_currency": "INR",
"link_expiry_time": "2025-11-08T13:03:44+05:30",
"link_id": "abff338e-f390-4b58-abab-849852e03d83",
"link_meta": {
"notify_url": "cloud.yellow.ai/api/galaxy/genericIntegration/cashfree/x1632218421575/cjnrfejn?id=3K4G//NmDGRj0bHGr1A91wspvXIMYjX/rKtcMVazrmk=",
"payment_methods": "upi",
"upi_intent": "true"
},
"link_minimum_partial_amount": null,
"link_notes": {
"product": "car",
"sender": "1410079569550798091459993047363",
"source": "yellowmessenger",
"uniqueId": "abff338e-f390-4b58-abab-849852e03d83"
},
"link_notify": {
"send_email": false,
"send_sms": false
},
"link_partial_payments": false,
"link_purpose": "This is to buy a game",
"link_status": "ACTIVE",
"link_url": "payments.cashfree.com/links/g9a0elgmqlp0",
"order_splits": [],
"terms_and_conditions": "",
"thank_you_msg": ""
}
```
-----
### Partial payment link generation
1. In the Automation flow builder, select the **Integrations** node and click **Cashfree** from the list of integrations that have been enabled for that AI agent.
2. After clicking **Cashfree**, an **Integration Action Node** will be added to the flow builder. When you click that node, you will see all use-cases of this integration in a drop-down. Choose **Partial payment link generation**.
3. Fill in all the mandatory fields. The below-mentioned table consists of the sample value, data type and description for all these fields.
| Field name | Sample value| Data type |Description |
| -------- | -------- | -------- |----|
Customer information | `{"customer_name": "John Doe","customer_phone": "9999999999","customer_email": "john@cashfree.com","customer_bank_account_number": 11111111111,"customer_bank_ifsc": "SBIN0001882","customer_bank_code": 7001}` | Object | Customer details including name, email, and phone number.
Amount | 100 | Number | The amount that should be the payment link. This must be in the smallest unit of the currency. For example, if you want to receive a payment of ₹299.95, you must enter the value 29995.
Currency | INR | String | Default is INR, we also accept payments in [international currencies](https://razorpay.com/docs/payments/international-payments/#supported-currencies).
Options | Reference details | Object | Custom options
First part payment amount | 50 | Number | Minimum amount in first installment that needs to be paid by the user if partial payments are enabled. This should be less than the link_amount.
Notes | `{"key_1": "value_1","key_2": "value_2"}` | Object | Key-value pair that can be used to store additional information about the entity. Maximum 5 key-value pairs
Enable partial payments | True or False | Boolean | Indicates whether customers can make partial payments using the payment link.Possible values:**true**: Customer can make partial payments.**false**: Customer cannot make partial payments.|
Link description | Payment for PlayStation 11 | String | A brief description for which payment should be collected.
Enable auto reminder | true or false | Boolean | If "true", reminders will be sent to users for collecting payments.
Link expiry time in ISO | 1 min | String | The timestamp after which the payment link will expire.
Notification options | `{ "email": true, "sms": true }` | Object | Defines how payment link notifications will be sent (via email, SMS, or both).
**Sample Success Response**
```json
{
"cf_link_id": 126602552,
"customer_details": {
"customer_name": "John",
"country_code": "+91",
"customer_phone": "9980056788",
"customer_email": "john.test@gmail.com"
},
"enable_invoice": false,
"entity": "link",
"link_amount": 100,
"link_amount_paid": 0,
"link_auto_reminders": false,
"link_created_at": "2025-10-09T13:15:49+05:30",
"link_currency": "INR",
"link_expiry_time": "2025-11-08T13:15:49+05:30",
"link_id": "d4c666e5-99d4-42d8-ab9a-1b8cf13c73d7",
"link_meta": {
"notify_url": "cloud.yellow.ai/api/galaxy/genericIntegration/cashfree/x1632218421575/cjnrfejn?id=3K4G//NmDGRj0bHGr1A91wspvXIMYjX/rKtcMVazrmk=",
"payment_methods": "upi",
"upi_intent": "true"
},
"link_minimum_partial_amount": null,
"link_notes": {
"product": "car",
"sender": "1410079569550798091459993047363",
"source": "yellowmessenger",
"uniqueId": "d4c666e5-99d4-42d8-ab9a-1b8cf13c73d7"
},
"link_notify": {
"send_email": false,
"send_sms": false
},
"link_partial_payments": true,
"link_purpose": "This is to buy a game",
"link_status": "ACTIVE",
"link_url": "payments.cashfree.com/links/F9a0g1oleor0",
"order_splits": [],
"terms_and_conditions": "",
"thank_you_msg": ""
}
```
A sample screenshot of Partial payment link generation:
----
**Reference**
For more information about action nodes to use in this integration, click [here](https://docs.cashfree.com/docs/payment-gateway).
---
## Ccavenue integration
**CcAvenue** is a leading payment gateway that allows businesses to securely accept online payments through credit cards, debit cards, net banking, and other methods.
By integrating CcAvenue with Yellow.ai, your AI agent can generate payment links directly within conversations, making transactions seamless and convenient for customers.
## Get configuration details from the CcAvenue portal
You need the following details to integrate CcAvenue with Yellow.ai:
* Merchant ID
* Environment (Sandbox or Production)
* Primary Working Key
* Access Codes and Working Keys for the listed IPs (these differ for Sandbox and Production environments).
To get these details from the CcAvenue portal, follow these steps:
1. Log in to your [CcAvenue dashboard](https://dashboard.ccavenue.com/).
2. Go to **Settings** > **API Key**.
3. Locate the first URL under API details (this will be your Primary URL).
4. Copy the **Working Key** associated with the Primary URL.
5. Collect the **Access Code** and **Working Key** for the specific IP addresses, as shown below:
### Connect CcAvenue to yellow.ai
:::note
* In a two-tier environment, connect the integration app in the Development environment.
* In a three-tier environment, connect it in Staging or Sandbox.
* Once connected, integrations are automatically available in the Live environment.
:::
To connect your CcAvenue account with Yellow.ai, follow these steps:
1. Navigate to the **Development/Sandbox** environment and
2. Go to **Extensions** > **Integrations** > **Payment** > **CcAvenue**. You can also search for **CcAvenue** in the search box.
3. In **Give account name**, enter a unique name for the integration. You can use only lowercase alphanumeric characters and underscores (_).
4. In **Merchant ID**, enter the ID copied from the CcAvenue portal.
5. In **Environment**, select Sandbox (testing) or Production (live).
6. In **Primary working key**, paste the key retrieved from API Key settings.
7. In **Access codes** and **Working keys**, enter the values for each IP address.
### Configure Webhook URL in CcAvenue account
The webhook URL acts as a callback endpoint where your CcAvenue account can send notifications or updates about payment events. This enables your AI agent or application to respond automatically when a payment status changes.
To configure the webhook URL, follow these steps:
1. Go to the connected **CcAvenue integration** and copy the **Webhook URL**.
2. Log in to your **CcAvenue account**, navigate to the **Webhook URL Configuration** section, and add the webhook URL you copied from Yellow.ai platform.
### Enable CcAvenue event to receive event in AI agent
You can enable payment status events to trigger actions in the AI agent once a transaction is completed.
1. On the [Cloud Platform](https://cloud.yellow.ai) go to Staging/Development environment.
2. On the left navigation bar, click **Automation** > **Event** > **Integrations** and search for `CcAvenue Payment Status`.
3. Click on the more options icon and select **Activate**. If multiple accounts are connected, activate the event for each one.
4. Once activated, create a flow under **Automation** > **Build**, and use this event as a trigger to display actions such as payment confirmation messages.
## Generate CcAvenue invoice link from AI agent conversation
1. When building [Conversation flows](https://docs.yellow.ai/docs/platform_concepts/studio/build/Flows/journeys), add an **Integration action node** and select **CcAvenue** from the list of enabled integrations.
2. When you click the node, you will see a drop-down with supported actions in this integration. Select **Generate Quick Invoice**.
3. Fill in the fields based on the details provided in the following table.
| Field name |Sample value | Data type|Description|
| -------- | -------- | -------- |-------|
Amount | 100 | Number | Amount to be paid using the payment link
Currency| INR | String | Cuurency for which the invoice to be generated
Customer Email ID | John@gmail.com |String | | Email ID on which the invoice will be sent.
Customer Email Subject | Invoice for your order | String | Subject line of the email containing the invoice.
Customer Mobile No | 9876543210 | Number | Mobile number of the customer
Customer Name | John Doe | String | Name of the customer receiving the invoice.
Valid for | 10 | Number | Duration for which the invoice remains valid.
Valid Type | days | Number | Unit of duration (minutes / hours / days / month / year).
Invoice Description | Payment for Order #123 | String | Description of the invoice (sent in email).
Merchant Reference No | INV123 | String | Unique merchant identifier for the invoice.
Sub Account ID | sub_001 | String | Unique sub-account ID (if applicable)
Terms and Conditions | All sales are final and non-refundable. | String | Terms and conditions to be displayed in the invoice.
**Sample response for success**
```c
{
"error_desc": "",
"invoice_id": "5393524984",
"tiny_url": "payit.cc/CCAVEN/IIt0JWU532",
"qr_code": "iVBORw0KGgoAAAANSUhEUgAAAH0AAAB9CAYAAACPgGwlAAACQUlEQVR42u3dQW7DMAwEQP__0-kLegjCpWhqFsglENxGY0CmZNnPR67LowugC3SBLtAFukAX6AJdoAt0gS7QBbpAF-gCXaBD__lgz1P--fb4_7VP_JZT_QAdOnToB9ETx0l3TtWJlO4H6NChQx-CXjUWf3v89ImU_lvQoUOHfiF61ZibvjaADh06dOjRH1s141c11kOHDh26Gbny8XrCdYVpWOjQob8UPb2e_pbv3UQBHTr0BeidSSyIJMq3kX0HHTp06PWzXumFj_StVlXt11_IQYcOfRN6Ynw8NTOW2IhxVckGHTr0G2bkJpdanXfDXrXgAh069E3oVaXcLyfSqbtk09uxoUOHDn3ImF7VJl3WVf1vnX0IHTp06ENKts5boTpn2CaUjdChQ4feXLJ1PqUhvf6eGH_X7GWDDh36zejpMuTUJoV02QgdOnTowxdcqhZQqhZcEm0SpeUrZuSgQ4d-A3rng_1PlV3pfXDX7k-HDh361s0OVVinTrbE_jjo0KFDX1ayVbXv_D5xzQAdOnTow0u2qpIn0SZRcqb3ykGHDh36wDG983ogXV6dekgRdOjQob90waWzczqfmLH-HS7QoUP_eFtTywJE5wt5q_pn5f506NChb0VPb1tOQ0-4boEOHTr0xejp8XHa4oi3KkOHDv1y9FOzf-njQIcOHfrlM3KntgxPeHIFdOjQoTejd25bnvAU6M5SFDp06NCb0eUdgQ5doAt0gS7QBbpAF-gCXaALdIEu0AW6QBfoAv3O_AEAhUV-1jUFZQAAAABJRU5ErkJggg",
"invoice_status": 0,
"error_code": "",
"merchant_reference_no": ""
}
```
Below is a sample screenshot of how the payment link will appear to the user:
---
## Integrate Yellow with CleverTap
The CleverTap integration allows you to create templates on Yellow.ai and run campaigns for your user base directly on CleverTap.
:::note
Contact your account administrator from CleverTap to configure the integration on CleverTap's end.
:::
## Limitations of CleverTap integration
The CleverTap integration does not support the following:
1. The text in a header cannot be dynamically changed.
2. Media formats supported within the header are png, jpg and mp4.
3. Error codes in callbacks from the WA server.
4. Dynamic quick replies.
## CleverTap Integration process
To integrate Yellow.ai with CleverTap, follow these steps -
1. On the Cloud platform, navigate to Development/Staging environment and go to **Extensions** > **Integrations** > **Tools & Utilities** > **CleverTap**. Alternatively, you can use the Search box to find a specific integration.
2. Generate and copy the API key and paste it with in the Authorization header over on CleverTap.
3. Enable Postback URL from Preferences in Engage. To know how to enable this from Preferences, see [Notification Engine](https://docs.yellow.ai/docs/platform_concepts/engagement/outbound/notification-engine#14-send-delivery-status-to-webhook).
4. Paste the callback URL generated by CleverTap in the fields shown on the integrations page.
5. Register `https://cloud.yellow.ai/integrations/genericIntegration/clevertap` as a static URL on the CleverTap dashboard to trigger Yellow.ai campaigns.
6. Generate regular templates through the [Template creation module](https://docs.yellow.ai/docs/platform_concepts/engagement/outbound/templates/overview) and use those template names directly in CleverTap.
7. To dynamically change text within a template, you can make use of **Freeform templates**. These will help you to pass dynamic text on CleverTap. For this, you need to generate two separate templates.
i. **Freeform text template**: This is a template with just a variable `{{1}}`. Once approved, you can pass the template as a field within the Integrations page.
ii. **Freeform media template**: This follows the same behaviour of the text template but with a media file attached at the time of approval. You can change the media dynamically changed over on CleverTap.
8. Once the templates are approved, pass both of these template names into the integration page fields.
9. Click **Connect**.
10. If you have multiple accounts, Click **+ Add account** and follow the above mentioned steps to add each of them. 2. You can add a maximum of 15 accounts.
:::note
1. Enter a unique name for each account to easily identify them within the yellow.ai platform. It is recommended to use a name that aligns with its purpose for better usability.
3. In a two-tier environment, such as bots with only Development/Live environments, you can add account names only in the development mode. Once added and flows have been built, in the Live mode, you can only choose the account names and not edit them.
4. In a three-tier environment, such as bots with Staging/Sandbox/Production modes, in Staging and Sandbox modes, you can add and edit new accounts. However, in Production, only the account details added in Staging will be available. You can only map in the production environment.
:::
---
## Creatio integration
Creatio CRM integration allows you to manage your Creatio account directly from the Yellow.ai platform. This integration allows you to get, create, and update user contacts from your Creatio account.
### Supported Creatio CRM actions in Yellow.ai
With this integration, you can perform the following Creatio CRM actions directly from the AI agent interface.
Action | Description
-------|-------------
Create a contact | Creates a new contact
Get a contact | Fetches a particular contact
Update a contact | Modifies details of a particular contact
### Get details from Creatio CRM account
Generate the required details - **Instance URL**, **Client ID**, **Client Secret**, and **API Base URL** -from your Creatio CRM account by following the steps below to integrate with Yellow.ai.
1. Log in to your Creatio account using your base URL.
Sample format: `https://{baseURL}.creatio.com`. Your login link may vary depending on the base URL assigned to your Creatio account.
2. Enter your **Username** and **Password**, then click **Login**.
3. Go to **System settings** > A**uthorization server URL for OAuth 2.0 integrations** > copy the **Default value**, which will be your **Instance URL**. For details, refer to the [Creatio setup guide](https://academy.creatio.com/docs/8.x/setup-and-administration/on-site-deployment/deployment-additional-setup/identity-service/set-up-the-identity-service-instruction).
4. From the Creatio home page, go to **Settings**.
5. Under **Import and integration**, select **OAuth 2.0 integrated applications**.
6. Cick **+ New** to create a new application.
7. Enter the following details:
* **Name**: Provide a name for the application.
* **Application URL**: Enter your application URL (example, https://creatio.com/). Note that, this field is optional.
* **Decription**: Enter a description relevant to the use case.
8. Click **Save**.
9. Open the application that you have created and copy the **Client Id** and **Client secret**.
10. From the Creatio application home page, copy the **Creatio API Base URL**.
### Connect Creatio CRM with Yellow.ai
You need to add accounts only in the development or staging environment. You can access the connected accounts in the Live/Production environment.
To connect your Creatio CRM account with Yellow.ai, follow the these steps:
1. On the left navigation bar, go to **Extensions** > **Integrations** > **CRM** > **Creatio**. Alternatively, you can use the Search box to find the integration app.
2. Under **Give account name**, provide a unique identifier. Only lowercase alphanumeric characters and underscores (`_`) are allowed.
3. In **Creatio API Base URL**, paste the URL that you have copied in step 10 of [Get configuration details from Creatio CRM account](#).
4. In **Instance URL**, paste the URL that you have copied from step 3 of [Get configuration details from Creatio CRM account](#).
5. In **Client ID** and **Client Secret**, paste the values that you have copied in the step of [Get configuration details from Creatio CRM account](#).
6. You can add up to 15 accounts. To add another Creatio CRM account, click on **Add account** and follow the steps mentioned above.
## Manage Creatio action in AI agent conversation
You can perform these Creatio actions directly from AI agent conversations
* [Create contact in your Creatio account](#create-user-details)
* [Fetch contact from your Creatio account](#get-user-details)
* [Update a contact ](#update-user-details)
### Create user details
To create a contact in your Creatio account, follow these steps:
1. Go to **Automation** and [create a flow](https://docs.yellow.ai/docs/platform_concepts/studio/build/Flows/journeys#2-create-a-flow) based on your requirement.
2. At the point in the flow where you want the AI agnet to interact with Creatio CRM, add the Creatio CRM node. For that, drag the node connector, go to **Integrations** > **Creatio**.
3. Click the node to view the drop-down with supported actions. Select **createEntity**.
4. Select the table you want to create. Based on your selection, all fields related to that table will be displayed.
5. Provide the details for all the required field.
**Sample response**
```c
{
"@odata.context": "mkpdev-2178.creatio.com/0/odata/$metadata#Contact/$entity",
"Id": "0e7fec10-40cc-42ac-b408-ad6269320b04",
"Name": "manish",
"OwnerId": "410006e1-ca4e-4502-a9ec-e54d922d2c00",
"CreatedOn": "2025-09-16T08:57:17.2377089Z",
"CreatedById": "410006e1-ca4e-4502-a9ec-e54d922d2c00",
"ModifiedOn": "2025-09-16T08:57:17.2377089Z",
"ModifiedById": "410006e1-ca4e-4502-a9ec-e54d922d2c00",
"ProcessListeners": 0,
"Dear": "manish",
"SalutationTypeId": "00000000-0000-0000-0000-000000000000",
"GenderId": "00000000-0000-0000-0000-000000000000",
"AccountId": "00000000-0000-0000-0000-000000000000",
"DecisionRoleId": "00000000-0000-0000-0000-000000000000",
"TypeId": "00000000-0000-0000-0000-000000000000",
"JobId": "00000000-0000-0000-0000-000000000000",
"JobTitle": "test job",
"DepartmentId": "00000000-0000-0000-0000-000000000000",
"BirthDate": "0001-01-01T00:00:00Z",
"Phone": "8816988208",
"MobilePhone": "8816988208",
"HomePhone": "8819223456",
"Skype": "testskype",
"Email": "manish@gmail.com",
"AddressTypeId": "00000000-0000-0000-0000-000000000000",
"Address": "haryana",
"CityId": "00000000-0000-0000-0000-000000000000",
"RegionId": "00000000-0000-0000-0000-000000000000",
"Zip": "127306",
"CountryId": "00000000-0000-0000-0000-000000000000",
"DoNotUseEmail": false,
"DoNotUseCall": false,
"DoNotUseFax": false,
"DoNotUseSms": false,
"DoNotUseMail": false,
"Notes": "notes test",
"Facebook": "manish sangwan",
"LinkedIn": "manishjum219",
"Twitter": "manishtwirte",
"FacebookId": "mansiFace",
"LinkedInId": "manishkumar219",
"TwitterId": "manis@twirtw",
"TwitterAFDAId": "00000000-0000-0000-0000-000000000000",
"FacebookAFDAId": "00000000-0000-0000-0000-000000000000",
"LinkedInAFDAId": "00000000-0000-0000-0000-000000000000",
"PhotoId": "00000000-0000-0000-0000-000000000000",
"GPSN": "dsfdsfsd",
"GPSE": "dfdsfdf",
"Surname": "sangwan",
"GivenName": "Test account ",
"MiddleName": "sang",
"Confirmed": true,
"Completeness": 0,
"LanguageId": "6ebc31fa-ee6c-48e9-81bf-8003ac03b019",
"Age": 0,
"IsEmailConfirmed": false,
"AdCampaignId": "00000000-0000-0000-0000-000000000000",
"CustomerNeedId": "00000000-0000-0000-0000-000000000000",
"ChannelId": "00000000-0000-0000-0000-000000000000",
"SourceId": "00000000-0000-0000-0000-000000000000",
"RegisterMethodId": "00000000-0000-0000-0000-000000000000",
"LeadConversionScore": 0,
"IsNonActualEmail": false,
"ContactPhoto@odata.mediaEditLink": "Contact(0e7fec10-40cc-42ac-b408-ad6269320b04)/ContactPhoto",
"ContactPhoto@odata.mediaReadLink": "Contact(0e7fec10-40cc-42ac-b408-ad6269320b04)/ContactPhoto",
"ContactPhoto@odata.mediaContentType": "application/octet-stream"
}
```
Below is a sample screenshot of how the response is generated when a new entity (contact) is created in your Creatio account:
### Get user details
1. Select **getEntity** action.
2. Select the table from which you want to get the user details.
* Once the table is selected, the fields will automatically display all the entities of that table in a dropdown. You can then directly select the entity for which you want to fetch the details.
3. Store response of the user in the variable of type object.
**Sample resposne**
```clike=
{
"@odata.context": "mkpdev-2178.creatio.com/0/odata/$metadata#Contact/$entity",
"Id": "be5b2bf3-f859-4e0a-9644-e41a59774068",
"Name": "Dwij jindal",
"OwnerId": "410006e1-ca4e-4502-a9ec-e54d922d2c00",
"CreatedOn": "2025-07-10T06:47:09.198782Z",
"CreatedById": "410006e1-ca4e-4502-a9ec-e54d922d2c00",
"ModifiedOn": "2025-07-10T06:47:09.198782Z",
"ModifiedById": "410006e1-ca4e-4502-a9ec-e54d922d2c00",
"ProcessListeners": 0,
"Dear": "",
"SalutationTypeId": "00000000-0000-0000-0000-000000000000",
"GenderId": "00000000-0000-0000-0000-000000000000",
"AccountId": "00000000-0000-0000-0000-000000000000",
"DecisionRoleId": "00000000-0000-0000-0000-000000000000",
"TypeId": "00000000-0000-0000-0000-000000000000",
"JobId": "00000000-0000-0000-0000-000000000000",
"JobTitle": "",
"DepartmentId": "00000000-0000-0000-0000-000000000000",
"BirthDate": "0001-01-01T00:00:00Z",
"Phone": "",
"MobilePhone": "+919876546497",
"HomePhone": "",
"Skype": "",
"Email": "Dwij@example.com",
"AddressTypeId": "00000000-0000-0000-0000-000000000000",
"Address": "",
"CityId": "00000000-0000-0000-0000-000000000000",
"RegionId": "00000000-0000-0000-0000-000000000000",
"Zip": "",
"CountryId": "00000000-0000-0000-0000-000000000000",
"DoNotUseEmail": false,
"DoNotUseCall": false,
"DoNotUseFax": false,
"DoNotUseSms": false,
"DoNotUseMail": false,
"Notes": "",
"Facebook": "",
"LinkedIn": "",
"Twitter": "",
"FacebookId": "",
"LinkedInId": "",
"TwitterId": "",
"TwitterAFDAId": "00000000-0000-0000-0000-000000000000",
"FacebookAFDAId": "00000000-0000-0000-0000-000000000000",
"LinkedInAFDAId": "00000000-0000-0000-0000-000000000000",
"PhotoId": "00000000-0000-0000-0000-000000000000",
"GPSN": "",
"GPSE": "",
"Surname": "jindal",
"GivenName": "Dwij",
"MiddleName": "",
"Confirmed": true,
"Completeness": 0,
"LanguageId": "6ebc31fa-ee6c-48e9-81bf-8003ac03b019",
"Age": 0,
"IsEmailConfirmed": false,
"AdCampaignId": "00000000-0000-0000-0000-000000000000",
"CustomerNeedId": "00000000-0000-0000-0000-000000000000",
"ChannelId": "00000000-0000-0000-0000-000000000000",
"SourceId": "00000000-0000-0000-0000-000000000000",
"RegisterMethodId": "00000000-0000-0000-0000-000000000000",
"LeadConversionScore": 0,
"IsNonActualEmail": false,
"ContactPhoto@odata.mediaEditLink": "Contact(be5b2bf3-f859-4e0a-9644-e41a59774068)/ContactPhoto",
"ContactPhoto@odata.mediaReadLink": "Contact(be5b2bf3-f859-4e0a-9644-e41a59774068)/ContactPhoto",
"ContactPhoto@odata.mediaContentType": "application/octet-stream"
}
```
Below is a sample screenshot of how the user details is fetched from your Creatio account:
### Update user details
1. Select **updateEntity** action.
2. Select the table from which you want to update the user details.
* Once the table is selected, the Select Object field will automatically display all the entities of that table in a dropdown. You can then directly select the entity for which you want to update the details.
3. Select the respective field for which you want to update the data. For example, user email.
**Sample response**
Below is a sample screenshot of how the user details is updated:
---
## Custom Live agent integration
## Overview
This document elaborates on the integration approach for a custom live agent to integrate with Yellow.ai. The following are the major use cases covered in this document:
1. End Customer wants to talk to an agent
2. End Customer sends Text/Image/Video/PDF ( or other media) to the Agent
3. The interaction details updated to end customer through ticket ID & details
4. Additional information about Agent Availability ( Queue Status, Typing status etc)
5. Agent connection established
6. Two-way communication between the end customer and agent
7. Closure of the ticket
:::info
Use **Ticket-closed** in the **Raise Ticket node** to perform specific actions when a live chat closes, instead of using the **ticket-close** event.
:::
### Design principles
1. The integration approach is defined to be channel agnostic, the 3rd party system should consider Yellow as the channel and Yellow will ensure that the end customer connects with an agent from any channel ( Web, WhatsApp etc.)
2. Details of the end customer's channel will be transferred to the 3rd party system for proper reconciliation.
3. The receiving system should be able to define custom parameters for their consumption and as needed for the business use case.
### Workflow Diagram
## Connect Custom Live chat account to Yellow.ai
1. On the left navigation bar, go to **Extensions** > **Integrations**.
2. Navigate to **Live chat** > **Custom live chat**. Alternatively, you can use the Search box to easily find it.
3. In **Give account name**, enter a unique account name for the integration. You can use only lowercase alphanumeric characters and underscores (\_).
4. Set up the remaining fields according to the descriptions provided in the table below.
| Field | Description |
| ------------------------------ | ---------------------------------------------------------------------------------------------------- |
| **Domain name** | The domain name associated with your live chat service. |
| **Company name** | The name of the company providing the live chat service. |
| **API key** | The key used to authenticate API requests. |
| **API timeout (in seconds)** | The maximum time, in seconds, to wait for an API response before timing out. (Default is 10 seconds.) |
| **Ticket queue message** | The message displayed to users when they are in the ticket queue. |
| **Send conversation history JSON** | Enable this option to allow sending conversation history (in JSON format) to the integrated account. For example, when providing context to support agents, debugging and analysis, and so on. |
| **Hide home button when user is in queue** | When enabled, the Home button is hidden while the user is waiting in the live chat queue. This prevents users from navigating away from the chat flow and ensures they remain in the queue until an agent responds. Default: Disabled.
| Hide input box when user is in queue | When enabled, the chat input box is hidden while the user is in the live chat queue. This helps avoid sending additional messages before the conversation begins with an agent. Default: Disabled
:::note
For older configurations, the options, `Hide home button when user is in queue` and `Hide input box when user is in queue` are disabled by default. You can edit the integration account to enable it manually.
:::
5. Click **Connect**.
6. If you have multiple accounts, click **+Add account** and follow the above mentioned steps to add each of them. You can add a maximum of 15 accounts.
## Connect custom live chat to your bot
1. In the **Automation** module, go to **Build** and navigate to the flow where you want to add the live agent flow.
2. In nodes selection, select **Integration** > **Raise a ticket** node.
| Option | Description |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Account name** | Choose the name of your live chat account. |
| **Message after ticket assignment** | Specify the message that should be sent after the ticket has been assigned to a live agent. |
| **Name** | Provide a name for the ticket. This is typically a label or identifier used to categorize or reference the ticket. |
| **Mobile** | Choose the mobile number associated with the ticket. This field helps in reaching out to users if required. |
| **Email (Optional)** | Choose the email address related to the ticket if you need to include it. |
| **Query** | Choose the subject, topic or query that will be addressed. This provides context for the ticket. |
3. To customize how your tickets are handled and processed, you can enable and configure **Advanced options**. These options allow you to set ticket priority, enable auto-translation, and add custom fields, tags, and departments.
| Option | Description |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Tags** | Enter appropriate tags for categorizing the ticket. Tags help in organizing and filtering tickets based on specific criteria. |
| **Group Code** | Assign a group code to the ticket if your system uses group codes for ticket routing or categorization. |
| **Priority** | Choose the priority level for the ticket to ensure it's handled according to its urgency. |
| **Translate user message** | Choose `Yes` to enable automatic translation of user messages. This feature translates messages into the desired language for better communication with agents. By default, it will be `No`. |
| **Voice ticket options** | If your system supports voice tickets, configure any relevant settings for handling voice-based interactions. |
| **Custom message** | Enable this option to personalize the notification sent to users when a ticket is assigned to an agent from queue. If enabled, you need to configure **Agent assignment text** as explained below. |
| **Agent assignment text** | Enter the message to be sent when a ticket is assigned to a live agent from queue. The text you enter here will replace the default system message. If a custom message is enabled but not set, or if the custom message option is disabled, the default notification will be sent automatically whenever a ticket is assigned to an agent from queue.**Default message**: "Your ticket number `{{body.ticketId}}` has been assigned to `{{body.agentName}}`." |
4. Use **Store response in** to save the user's response to a variable. You can also create a new variable to store the response for future use.
---
## Business use cases
### Initiate conversations
An end customer who uses the bot, will encounter the following action while connecting with a live agent
1. Bot gives an option to connect to a Live Agent.
2. Bot goes into a paused state once the agent gets connected.
3. When the bot is in paused state, the 2-way communication between the agent and end customer takes place.
4. Once the agent ends the conversation, the bot takes over.
### Business Use Cases Supported by Third-Party Tool
| # | Use Case | Required | Remarks |
|----|--------------------------------|----------|-----------------------------------------------------------------------------------------------------------------------------|
| 1 | Send Message `{text + media}` | Yes | Chat history will be present in the first message as a link |
| 2 | Send typing event | No | |
| 3 | Create Ticket | Yes | Response should contain `ticketID`Scenarios (Ticket Lifecycle):1. Request is in queue2. Ticket is created & OPEN3. Ticket is created & ASSIGNED |
| 4 | User details `{Channel ID, Sender ID, Unique ID}` | Yes | |
| 5 | Transfer to a particular group | No | Department-wise, as per business need |
| 6 | Ability to pass custom parameter | Yes | |
| 7 | Is User Active | No | |
| 8 | Custom Parameters | Yes | Ability to pass custom parameters as per business need |
|
### Enable conversation
The following are the use cases & details required for a two-way communication between a third party system & Yellow.ai.
:::note
For this, Yellow's webhook must be configured at third party systems end.
:::
| S.no | Type | Required | Remarks |
| ---- | ---------------------------------------------------------- | -------- | -------------------------------------------------------------------- |
| 1 | Event name/code specification | Yes | |
| 2 | Agent message `{text + media}` | Yes | |
| 3 | Agent assigned `{along with agent details}` | Yes | Agent details like agent name, department should be received |
| 4 | Queue Positioning | No | |
| 5 | Closed ticket | Yes | Closed ticket event |
| 6 | Updation of any ticket detail (e.g. transferred to another agent) | No | |
| 7 | Is Agent active? | No | |
---
## API Specification
The header that will be common across all the APIs which the third party needs to create is an auth token:
```http
Authorization: `{{token}}`
Content-Type: application/json
```
### Create ticket
| URL | `{{domainName}}createTicket/{{companyName}}` |
| ------ | --------------------------------------------- |
| METHOD | POST |
#### Body parameters
| Name | Data type | Description | Mandatory |
| ------------------------- | --------- | ---------------------------------------------------------------------------------------------- | --------- |
| senderId | string | Unique identifier of the user generated by Yellow.AI | Y |
| messageId | string | Unique identifier of every sent message | Y |
| source | string | Channel from where the message can be sent | Y |
| conversationId | string | Unique identifier of this conversation | Y |
| userName | string | Name of the user/customer | Y |
| userMobile | string | Mobile number of the user, accepts 10 digit mobile number | Y |
| userEmail | string | Email Id of the user | Y |
| conversationHistory | string | The URL of the conversation prior to connecting to the agent | Y |
| ticketPriority | string | Priority of the ticket, possible values low/medium/high | Y |
| ticketCategory | string | Category to which a ticket may belong | N |
| ticketGroupId | string | If we want the ticket to get assigned to a particular group of agents, we need to add this | N |
| customFields | object | Use this if any custom key value pairs need to be passed. The data type of the values can be string/number/boolean/object | N |
| conversationHistoryJSON | array | The JSON of the conversation prior to connecting to the agent | N |
#### CURL
```bash
curl --location --request POST '{{domainName}}createTicket/{{companyName}}' \
--header 'Authorization: Bearer `{{token}}`' \
--header 'Content-Type: application/json' \
--data-raw '{
"body": {
"user": {
"userName": "Shubh",
"userMobile": "99999999",
"senderId": "11111111211111",
"userEmail": "test@gmail.com"
},
"ticket": {
"conversationHistory": "https://google.com",
"source": "web",
"ticketPriority": "medium",
"ticketCategory": "sales",
"conversationId": "efrfrfrfr",
"ticketGroupId": "14343",
"customFields": {}
}
}
}'
```
#### Response
```json
{
"status": "success/failure",
"data": {
"ticketId": 25633,
"isAgentAvailable": true,
"isQueued": false
},
"message": ""
}
```
:::note
If queuing is enabled, the `createTicket` API should respond with `isAgentAvailable: false` and `isQueued: true`.
:::
### Send message to Agent
| URL | `{{domainName}}sendMessage/{{companyName}}` |
| ------ | ------------------------------------------- |
| METHOD | POST |
#### Body parameters
| Name | Data type | Description | Mandatory |
| -------------- | --------- | ------------------------------------------------ | --------- |
| senderId | string | Unique identifier of the user generated by Yellow.ai | Y |
| userName | string | Name of the user | Y |
| userEmail | string | Email Id of the user | N |
| message | string | Message sent by the user | Y |
| messageId | string | Unique identifier of every sent message | Y |
| ticketId | string | Generated ticketId from API 1 | Y |
| source | string | Channel in which the message can be sent | Y |
| conversationId | string | Unique identifier of this conversation | Y |
| messageType | string | Type of the message sent,the value will be **text** | Y |
#### CURL
```bash
curl --location --request POST '{{domainName}}sendMessage/{{companyName}}' \
--header 'Authorization: Bearer `{{token}}`' \
--header 'Content-Type: application/json' \
--data-raw '{
"body": {
"user": {
"senderId": "11111",
"userName": "Mahesh",
"userEmail": "test@gmail.com"
},
"ticket": {
"messageType": "text",
"message": "hello",
"messageId": "efefe-eefe-fefef-feefefe",
"ticketId": "275333",
"source": "web",
"conversationId": "yguyegdee"
}
}
}'
```
#### Response
```json
{
"status": "success/failure",
"data": {
"ticketId": 25633
},
"message": ""
}
```
### Send user media to Agent
| URL | `{{domainName}}sendMedia/{{companyName}}` |
| ------ | ----------------------------------------- |
| METHOD | POST |
#### Body parameters
| Name | Data type | Description | Mandatory |
| -------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------- | --------- |
| senderId | string | Unique identifier of the user generated by Yellow.AI | Y |
| userName | string | Name of the user | Y |
| userEmail | string | Email Id of the user | N |
| mediaJson | object | Has two properties. The first property is "type", and its possible values are image/video/file. The second property is "url" which will have the url of the media | Y |
| messageId | string | Unique identifier of every sent message | Y |
| ticketId | number | Generated ticketId from API 1 | Y |
| source | string | Channel in which the message is sent | Y |
| conversationId | string | Unique identifier of this conversation | Y |
| messageType | string | Type of the message sent, the value will be media | Y |
#### CURL
```bash
curl --location --request POST '{{domainName}}sendMedia/{{companyName}}' \
--header 'Authorization: Bearer `{{token}}`' \
--header 'Content-Type: application/json' \
--data-raw '{
"body": {
"user": {
"senderId": "11111",
"userName": "Mahesh",
"userEmail": "test@gmail.com"
},
"ticket": {
"messageType": "media",
"mediaJson": {
"type": "image/video/file",
"url": "https://image.com"
},
"messageId": "efefe-eefe-fefef-feefefe",
"ticketId": "275333",
"source": "web",
"conversationId": "yguyegdee"
}
}
}'
```
#### Response
```json
{
"status": "success/failure",
"data": {
"ticketId": 25633
},
"message": ""
}
```
## Webhook
| Field | Description |
|------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **URL** | `https://{{host}}/integrations/genericIntegration/custom-live-agent`**Note:**- `host` pattern: `{rCode}.cloud.yellow.ai`- `r1`: MEA- `r2`: Jakarta- `r3`: Singapore- `r4`: USA- `r5`: Europe- For India: omit `rCode` |
| **Method** | `POST` |
| **x-auth-token** | Provided by Yellow.ai |
| **Response Code**| `200` |
---
### Text Message Sent by the Agent
**Event:**
`payload-received-from-agent`
---
#### Payload
```json
{
"ticketId": 354545,
"senderId": "efrf",
"source": "erfr4rf4",
"event": "payload-received-from-agent",
"message": {
"type": "text",
"payLoad": {
"content": "Hello"
}
},
"agentName": "gefgeuf",
"agentId": "locobuzzagentId",
"ticketAssignedTime": 3545454
}
```
---
#### Response
```json
{
"status": "success",
"data": {
"ticketId": 354545,
"senderId": "efrf",
"source": "erfr4rf4",
"event": "payload-received-from-agent",
"message": {
"type": "text",
"payLoad": {
"content": "Hello"
}
},
"agentName": "gefgeuf",
"agentId": "locobuzzagentId",
"ticketAssignedTime": 3545454
},
"message": ""
}
```
### Media message sent by the Agent
### Media Message Sent by the Agent
**Event:**
`payload-received-from-agent`
**Payload**
```json
{
"ticketId": 354545,
"senderId": "efrf",
"source": "erfr4rf4",
"event": "payload-received-from-agent",
"message": {
"type": "media",
"payLoad": {
"content": {
"type": "image/video/file",
"mediaUrl": "https://www.google.com"
}
}
},
"agentName": "gefgeuf",
"agentId": "locobuzzagentId",
"ticketAssignedTime": 3545454
}
```
**Response**
```json
{
"status": "success",
"data": {
"ticketId": 354545,
"senderId": "efrf",
"source": "erfr4rf4",
"event": "payload-received-from-agent",
"message": {
"type": "media",
"payLoad": {
"content": {
"type": "image/video/file",
"mediaUrl": "https://www.google.com"
}
}
},
"agentName": "gefgeuf",
"agentId": "locobuzzagentId",
"ticketAssignedTime": 3545454
},
"message": ""
}
```
---
### Ticket Assignment to the Agent
**Event:**
`ticket-assigned`
**Payload**
```json
{
"ticketId": 354545,
"senderId": "efrf",
"source": "erfr4rf4",
"event": "ticket-assigned",
"agentName": "gefgeuf",
"agentId": "locobuzzagentId",
"ticketAssignedTime": 3545454
}
```
**Response**
```json
{
"status": "success",
"data": {
"ticketId": 354545,
"senderId": "efrf",
"source": "erfr4rf4",
"event": "ticket-assigned",
"agentName": "gefgeuf",
"agentId": "locobuzzagentId",
"ticketAssignedTime": 3545454
},
"message": ""
}
```
---
### Ticket Closure
**Event:**
`ticket-closed`
**Payload**
```json
{
"ticketId": 354545,
"senderId": "efrf",
"source": "erfr4rf4",
"event": "ticket-closed",
"agentName": "gefgeuf",
"agentId": "locobuzzagentId",
"ticketAssignedTime": 3545454,
"ticketResolvedTime": 4545454
}
```
**Response**
```json
{
"status": "success",
"data": {
"ticketId": 354545,
"senderId": "efrf",
"source": "erfr4rf4",
"event": "ticket-closed",
"agentName": "gefgeuf",
"agentId": "locobuzzagentId",
"ticketAssignedTime": 3545454,
"ticketResolvedTime": 4545454
},
"message": ""
}
```
---
### Agent Logout During the Conversation (After Working Hours)
**Event:**
`agent-logout`
**Payload**
```json
{
"ticketId": 354545,
"senderId": "efrf",
"source": "erfr4rf4",
"event": "agent-logout",
"agentName": "gefgeuf",
"agentId": "locobuzzagentId",
"ticketAssignedTime": 3545454
}
```
**Response**
```json
{
"status": "success",
"data": {
"ticketId": 354545,
"senderId": "efrf",
"source": "erfr4rf4",
"event": "agent-logout",
"agentName": "gefgeuf",
"agentId": "locobuzzagentId",
"ticketAssignedTime": 3545454
},
"message": ""
}
```
---
### Agent Logged In but Not Active in the Conversation
**Event:**
`agent-inactivity`
**Payload**
```json
{
"ticketId": 354545,
"senderId": "efrf",
"source": "erfr4rf4",
"event": "agent-inactivity",
"agentName": "gefgeuf",
"agentId": "locobuzzagentId",
"ticketAssignedTime": 3545454,
"inactivityDuration": 120,
"inactivityReason": "Network issue"
}
```
**Response**
```json
{
"status": "success/failure",
"data": {
"ticketId": 354545,
"senderId": "efrf",
"source": "erfr4rf4",
"event": "agent-inactivity",
"agentName": "gefgeuf",
"agentId": "locobuzzagentId",
"ticketAssignedTime": 3545454,
"inactivityDuration": 120,
"inactivityReason": "Network issue"
},
"message": ""
}
```
This updated file should no longer cause any build errors. Let me know when you're ready for the next batch of files.
---
## Entrust integration
The **Entrust** integration connects your automation or agent to **Entrust Identity as a Service (IDaaS)** using the **Administration API**. After you connect with an API application's credentials, you can look up users, create and update accounts, reset passwords, change activation state, unlock users, manage organizations, run paged searches, and (where your tenant supports it) sync users with a directory.
This page walks you from **Entrust portal setup** through **field-by-field configuration** and **each supported action**, so you can use the integration without guesswork.
---
## What you can do
| Area | Capabilities |
|------|----------------|
| **Read** | Get user by UUID, by login **userId**, by **externalId**; list users with filters and paging (v4). |
| **Write** | Create / update / delete one user or many; update multiple users in one call; modify organization membership. |
| **Security & access** | Set or reset password (temporary password and force change on next login); unlock account; set **ACTIVE** / **INACTIVE**. |
| **Directory** | Synchronize or unsynchronize a user with AD/LDAP (requires IDaaS directory + Gateway 5.0+). |
All of this is backed by Entrust's **Administration API**; you interact through named actions in Yellow (for example **Get user by UUID**, **Create a user**), not by typing URLs.
---
## Prerequisites
Before you configure the integration in Yellow:
1. **Entrust IDaaS tenant** with Administration API access as documented by Entrust for your environment.
2. **Administration API application** created in the **Entrust IDaaS Administration Portal** under **Applications** (or equivalent in your portal).
3. From that application, you will need:
- **Application ID**
- **Shared secret**
4. Your tenant's **API base URL** exactly as Entrust provides it (scheme + host, and path prefix if your tenant uses one—**no trailing slash**).
5. **API permissions** on the application must match what you intend to run. Missing access usually shows as **403** with a message such as **`USERS:VIEW required`**. See [Required API permissions](#required-api-permissions) below.
---
## Step 1: Create and scope the Administration API app (Entrust portal)
1. Sign in to the **Entrust IDaaS Administration Portal**.
2. Open **Applications** (or your portal's equivalent) and create or select an **Administration API** application.
3. Copy **Application ID** and **shared secret** into a secure location (password manager). Treat the shared secret like a password.
4. Enable only the **API permissions** your flows need (principle of least privilege). Use the [permission reference](#required-api-permissions) to match actions to scopes.
5. Confirm the **API base URL** for your tenant (from Entrust documentation or your admin). Examples are tenant-specific; always use the value Entrust gives you.
---
## Step 2: Configure the integration in Yellow
1. Open your **Integrations** (or **App configuration**) area and add **Entrust**.
2. Fill in the three required fields:
| Field | What to enter | Tips |
|--------|----------------|------|
| **API base URL** | Full base URL for your tenant's API | No trailing `/`. Wrong host or unreachable URL causes connectivity errors. |
| **Application ID** | From the Administration API application | Pasted exactly; no extra spaces. |
| **Shared secret** | From the same application | Never commit to source control or share in plain chat. |
3. **Access token** is managed for you: after a successful sign-in, Yellow keeps the session token and uses it automatically for each action. You do not need to paste or refresh a token by hand under normal use.
4. Click **Connect** (or your product's **Save / Verify**). Yellow checks your **Application ID** and **shared secret** with Entrust. On success you should see that **Entrust Administration API credentials verified**; after that, your flows can run the actions below.
### Validation behavior
- **Success**: You should see a message that **Entrust Administration API credentials verified**.
- **Failure (401)**: Usually wrong Application ID or shared secret. Re-copy from the portal and try again.
- **Unreachable host (`ENOTFOUND` or similar)**: Check **API base URL** (typo, wrong region, VPN, or DNS).
---
## Authentication and token refresh
- **Signing in**: The first time you connect—and whenever needed—Yellow signs in to Entrust using your **Application ID** and **shared secret** stored in the integration.
- **Running actions**: You only pick an action and fill its fields; Yellow attaches the active session automatically.
- **If the session expires**: A **401** / "authentication failed or token expired" style error usually triggers a fresh sign-in in the background. If problems persist, reconnect from the integration card and confirm the app is still enabled in the Entrust portal.
---
## Required API permissions
Grant your Administration API application only what you need. The integration surfaces friendly errors that name the permission when Entrust returns **403**.
| Permission | Typical actions |
|------------|------------------|
| **USERS:VIEW** | Get user by UUID / userId / external ID; **List a page of users**; read-style responses. |
| **USERS:ADD** | **Create a user**; **Create multiple users**. |
| **USERS:EDIT** | **Update a user**; **Update multiple users**; **Modify user organization**; **Update user state**; **Unlock user**; **Synchronize user**; **Unsynchronize user**. |
| **USERS:REMOVE** | **Delete a user**; **Delete multiple users**. |
| **USERPASSWORDS:EDIT** | **Set temporary password** (reset password endpoint). |
If an action fails with **Insufficient permissions (... required)**, add that scope in the Entrust portal for the same API application, then reconnect or retry.
---
## Field conventions: what goes where
Some actions ask for **User UUID** only as a **separate field** (used to identify the account). Do not repeat that UUID in the extra payload fields unless the form explicitly asks for it there too.
- **User UUID as its own field** (not duplicated in the payload): get by UUID, set password, update state, unlock, update user, delete user, modify organization.
- **User ID in the payload**: **Get user by user ID** uses the login **userId** in the request body. **Get user by external ID** is special—the form still uses a field labeled for external ID, but Entrust expects it under the property name **`userId`** in the body (see that section below).
---
## Actions (configuration and usage)
For each action, fill the **required** fields in your flow or integration step. Optional fields can be left empty unless you need them. Simple examples below are illustrative—use real values from your tenant.
**Typical wait times**: Lookups and small updates usually finish in a few seconds. Creating or updating users, bulk jobs, directory sync, and large paged lists may take longer (up to about a minute in heavy cases).
### Get user by UUID
- **Purpose**: Fetch a single user by internal UUID.
- **Required**: **User UUID** (the Entrust internal id for that person).
- **Permissions**: `USERS:VIEW` (typical).
- **Success data** (illustrative): `id`, `userId`, `state`, `locked`, `email`, `firstName`, `lastName`, … (exact fields per Entrust API version).
- **Errors**: **401** → authentication failed or token expired; **404** → user not found.
### Get user by user ID
- **Purpose**: Lookup by login **userId** (username).
- **Required**: **User ID** (the username / login id the person uses to sign in).
- **Permissions**: `USERS:VIEW`.
- **Errors**: **401**, **404** (user not found).
### Get a user by external ID
- **Purpose**: Lookup by **external ID** stored on the user (often the id from your HR or source system).
- **Important**: This is **not** the same as **Get user by user ID** (login name). Use the action meant for **external ID** and enter the id from your other system.
- **Required**: The **external ID** value to look up.
- **Permissions**: `USERS:VIEW`.
- **Errors**: **401**, **403**, **404**.
### List a page of users
- **Purpose**: Search the user directory **one page at a time**. If you add several search rules, Entrust treats them as **AND** (all must match).
- **Required**: Nothing—everything below is optional.
- **Optional fields**:
- **Page size (`limit`)**: How many users per page (**1–100**).
- **Cursor**: Copy from the **previous** response to fetch the **next** page. When you use a cursor, **search and sort options are ignored** for that call—use the cursor alone to continue paging.
- **Search filters**: List of rules; each rule has an attribute **name**, an **operator** (such as equals, contains, greater than, "in list", exists / not exists, and others), and usually a **value**. Which operators work on which attributes is defined by Entrust—use their Administration API documentation for the full matrix. Common filter names include **userId**, **state**, **locked**, **organizationId**, **lastAuthTime**, and more.
- **Sort**: Sort field (often **userId**, **state**, or **lastAuthTime**) and ascending / descending.
- **Extra data per user**: Optional add-ons such as groups, roles, tokens, aliases, organizations, etc., depending on what your tenant supports.
- **Permissions**: `USERS:VIEW`.
- **Errors**: **400** invalid search/limit/paging; **401**; **403** with `USERS:VIEW required` message when permission missing.
### Create a user
- **Purpose**: Create one user.
- **Required**: **First name**, **Last name**, **Email**, **User ID** (the login id you want in Entrust).
- **Optional** (examples—you can add as many as your form offers): grace period, verification email, external id/source, groups and organizations, locale, phone and mobile, OTP delivery preference (**EMAIL**, **SMS**, **VOICE**, or **SYSTEM**), registration / verification flags, **ACTIVE** / **INACTIVE** state, security id, aliases, and extended attribute blocks. Use Entrust's docs for advanced attribute shapes.
- **Permissions**: `USERS:ADD`.
- **Errors**: **401**; **403** `USERS:ADD required`; **400** validation; **409** user ID or alias already exists.
### Update a user
- **Purpose**: Update profile and related fields for one user.
- **Required**: **User UUID** of the account to change, plus whichever profile fields you are updating.
- **Optional fields**: Same kinds of details as **Create a user** (email, names, groups, organizations, state, OTP preferences, and so on). **User ID** (login) can be changed on update only if your process requires it—it is not required every time.
- **Permissions**: `USERS:EDIT`.
- **Errors**: **401**; **403** `USERS:EDIT required`; **400**; **404** not found; **409** user ID or alias conflict.
### Delete a user
- **Purpose**: Delete one user by UUID.
- **Required**: **User UUID** of the account to remove.
- **Permissions**: `USERS:REMOVE`.
- **Errors**: **401**; **403** `USERS:REMOVE required`; **404**.
### Modify user organization
- **Purpose**: Replace the user's **organization membership** with the given list.
- **Required**: **User UUID**; **Organizations** (list of organization UUIDs the user should belong to after the change).
- **Permissions**: `USERS:EDIT`.
- **Errors**: **401**; **403**; **404**.
### Set temporary password
- **Purpose**: Set password for a user; control temporary flag and forced change on next login.
- **Required**: **User UUID**; **New password**; whether it is a **temporary password**; whether to **force change on next login**.
- **Note**: Enter the **User UUID** in its own field; fill password and flags only in their dedicated fields—do not duplicate the UUID inside the password payload.
- **Permissions**: `USERPASSWORDS:EDIT`.
- **Errors**: **401**; **403** `USERPASSWORDS:EDIT required`.
### Update user state
- **Purpose**: Set account state to **ACTIVE** or **INACTIVE**.
- **Required**: **User UUID**; **State** (`ACTIVE` or `INACTIVE`).
- **Permissions**: `USERS:EDIT`.
- **Errors**: **401**; **403** `USERS:EDIT required`; **404**.
### Unlock user
- **Purpose**: Unlock a locked user account.
- **Required**: **User UUID** of the account to unlock.
- **Permissions**: `USERS:EDIT`.
- **Errors**: **401**; **403**; **404**.
### Create multiple users
- **Purpose**: Create **many users in one** request.
- **Required**: A **users** list. Each person usually needs at least **first name**, **last name**, **email**, and **user ID** (your tenant may require more—match what you use for **Create a user**). You can add the same optional details as when creating one user.
- **Optional**: **Stop on error**—when **on**, stop after the first failed row; when **off**, keep trying the rest (default is **off** if you leave it unset).
- **Permissions**: `USERS:ADD`.
- **Errors**: **401**; **403**; **400** validation on one or more items; **409** duplicate user ID or alias.
### Update multiple users
- **Purpose**: Batch update different users in one call.
- **Required**: A **users** list. Each row must include:
- **Id**: The value that identifies the person (see **Id type**).
- **Id type**: **`UUID`** (internal id), **`USERID`** (login id), or **`EXTERNALID`**. If you skip this, Entrust usually treats **Id** as a UUID.
- **Changes**: Only the profile fields you want to change for that person; every field inside this block is optional—omit what should stay the same.
- **Optional**: **Stop on error** (default **off**). When **on**, the batch stops at the first failure; when **off**, remaining users are still attempted.
- **Changes** supports the same kinds of fields as **Update a user** (email, names, state, groups, organizations, OTP preferences, and so on).
- **Permissions**: `USERS:EDIT`.
- **Errors**: **401**; **403** `USERS:EDIT required`; **400** invalid request or validation failures.
### Delete multiple users
- **Purpose**: Batch delete users.
- **Required**: A **users** list; each row needs an **Id**. **Id type** is optional (**UUID**, **USERID**, or **EXTERNALID**; if omitted, **Id** is usually treated as a UUID).
- **Optional**: **Stop on error** (same meaning as in other bulk actions).
- **Permissions**: `USERS:REMOVE`.
- **Errors**: **401**; **403**; **400**.
### Synchronize user
- **Purpose**: Sync a user with **AD/LDAP** via IDaaS (requires **directory** + **Gateway 5.0+** in your environment).
- **Required**: **Directory ID** (the directory's UUID in Entrust); **User id** (the internal UUID or login id, depending on **Id type** below).
- **Optional**: **Id type**—**UUID** or **USERID** only (**external ID** is not supported here). If you leave it out, Entrust usually assumes **USERID**.
- **Permissions**: `USERS:EDIT`.
- **Errors**: **401**; **403**; **400** invalid directory, user id, or sync configuration.
### Unsynchronize user
- **Purpose**: Remove AD sync so the user becomes **locally managed**; re-enable sync with **Synchronize user** later.
- **Required**: **User id** (internal UUID or login id, depending on **Id type**).
- **Optional**: **Id type**—**UUID** or **USERID** only (defaults to **USERID**); **external ID** is not supported here.
- **Permissions**: `USERS:EDIT`.
- **Errors**: **401**; **403**; **400** invalid user or unsync not allowed.
---
## Shared field reference (create, update, and bulk "changes" blocks)
Use the same values across **Create a user**, **Update a user**, and the per-user **changes** section in **Update multiple users**:
- **`locale`**: `da`, `de`, `en`, `es`, `fr`, `it`, `ja`, `ko`, `nl`, `nb`, `pl`, `pt`, `ru`, `sv`, `th`, `tr`, `zh-cn`, `zh-tw`.
- **`preferredOtpDelivery`**: `EMAIL`, `SMS`, `VOICE`, `SYSTEM`.
- **`state`**: `ACTIVE`, `INACTIVE`.
- **Arrays**: `groups`, `oauthRoles`, `organizations` expect **UUID** strings unless your tenant documentation specifies otherwise.
- **Complex**: `userAliases`, `userAttributeValues`, `userExtraAttributes`, `preferredOtpDeliveryContactAttributes` follow Entrust's object shapes. When in doubt, copy structure from an existing user you exported from Entrust or from Entrust's own Administration API guides.
---
## Error handling (what you will see)
### Integration-level (connect / network)
- **API base URL not reachable** (host not found / connection errors): Fix URL, DNS, VPN, or firewall; ensure **no trailing slash** on base URL.
- **Authentication failed (401)** on connect: Wrong **Application ID** or **shared secret**—re-verify in the Administration Portal.
### Action-level (common error codes)
| Code | Typical meaning | What to do |
|------|-----------------|------------|
| **401** | Session or credentials problem | Reconnect from the integration card or retry; Yellow may renew the session automatically. |
| **403** | Missing Entrust permission | Add the named permission to the API application in Entrust. |
| **404** | User not found | Check **User UUID**, login **User ID**, **Id type** in bulk actions, or use the correct lookup action. |
| **400** | Invalid or incomplete request | Fix required fields, allowed values, or filters. |
| **409** | Conflict | Duplicate **User ID** or alias when creating or updating. |
If a message hints at **your** credentials or integration settings, fix those first; if it points to bad or missing user data, adjust the fields you passed into the action.
---
## Best practices
1. **Least privilege**: Start with read-only scopes; add `USERS:ADD`, `USERS:EDIT`, `USERS:REMOVE`, or `USERPASSWORDS:EDIT` only when needed.
2. **Secrets**: Rotate shared secrets in Entrust if exposed; update the integration immediately after rotation.
3. **Base URL**: Copy from Entrust docs or admin UI; avoid guessing regional hostnames.
4. **Bulk operations**: Use **`stopOnError: true`** when you need all-or-nothing semantics; use **`false`** for best-effort partial success (confirm behavior with Entrust response bodies in your environment).
5. **Paging**: For large directories, use **List a page of users** with **`limit`** and **`cursor`** rather than assuming a single response returns everyone.
6. **External ID lookup**: Use the **external ID** value in the action meant for that lookup; do not confuse it with the login **user ID** action.
---
## Troubleshooting checklist
1. **Connect fails immediately** → Check **API base URL** (reachable, no trailing slash), **Application ID**, **shared secret**.
2. **403 on a specific action** → Compare action to [permission table](#required-api-permissions); update Entrust app scopes.
3. **404 on get** → Wrong UUID or wrong **Id type** in bulk updates; for external lookup, use **Get user by external ID** and the value from your source system.
4. **409 on create/update** → User ID or alias collision; pick a unique `userId` or adjust aliases.
5. **400 on list users** → Invalid `limit` (must be 1–100), invalid filter combination, or **`cursor`** used together with incompatible search options.
6. **Sync / unsync errors** → Confirm directory ID, Gateway version, and that **EXTERNALID** is not used on sync endpoints.
---
## Summary
Configure **API base URL**, **Application ID**, and **shared secret** from an Entrust **Administration API** application, then **Connect** so Yellow can sign in and keep the session for you. Pick actions that match the permissions you enabled in Entrust, use **User UUID** only where the form asks for it, and use **Get user by external ID** (not login lookup) when you have an external system id. Use **bulk** and **List a page of users** when you have many accounts. For unusual profile fields, rely on Entrust's Administration API documentation together with the field lists above.
---
## EPIC FHIR Integration
The Epic FHIR integration lets your bot access medical records from your Epic FHIR app and manage patient details, search for appointment slots, and book appointments.
## Supported Epic FHIR actions with Yellow.ai
After integrating with Epic FHIR, you can perform the following tasks directly from the Yellow.ai platform:
| Action| Description |
| -------- | -------- |
| Fetch patient information | Fetch patient information from patient ID |
|Fetch patient diagnostic information| Fetch patient diagnostic information from patient ID|
|Fetch patient demographics| Fetch patient information using the patient's date of birth and name|
|Fetch appointment slots|Fetch available appointment slots|
|Book appointments|Book appointments with the available appointment ID from fetch appointment slots use case|
Fetch patient appointment details| Fetch the appointment details of a patient from the patient ID|
## Connect Epic FHIR with Yellow.ai
**Prerequsites:**
1. An app on Epic FHIR. To know about creating an app on Epic FHIR, click [here](https://fhir.epic.com/Documentation?docId=epiconfhirrequestprocess).
2. An active yellow.ai account.
To connect your Epic FHIR account with Yellow.ai, follow the these steps:
1. Go to your app on Epic FHIR and copy the **Client ID** and **Client Secret**.
2. On the left navigation bar, go to **Extensions** > **Integrations** > **CRM** > **EPIC FHIR**. Alternatively, you can use the Search box to find the integration app.
3. Enter the **Client ID** and **Client Secret** and click **Connect to EPIC FHIR**.
:::info
1. In a two-tier environment, add account names in Development and use them in Live.
2. In a three-tier environment, add accounts in Staging and Sandbox, and they'll be available in Production.
:::
4. You can add up to 15 accounts. To add another Epic FHIR account, click on **Add account** and follow the steps mentioned above.
:::note
1. Yellow.ai does not store the client’s credentials. We use the OAuth 2.0 approach to integrate with the client’s **Epic FHIR** account.
2. This integration supports the STU3 version of API, so the APIs based on the clients' use cases should be added while creating the **Epic** app.
:::
## Use actions in bot conversations
This integration lets your users access patient's medical records and fetch/book appointments.
1. Go to **Automation** and build a flow based on how you want the bot to take the user through the process.
2. Include the integration node at the point in the flow where you want to let the user access Epic FHIR info. To accomplish this, navigate to **Integrations** and select **EPIC FHIR**.
3. Once the node gets added, click the node, choose the EPIC FHIR account for that action and [choose the action](#supported-epic-fhir-actions-with-yellowai) you want to carry out.
4. Depending on the selected action, the corresponding fields will be shown. Collect this information as input from users by constructing a flow accordingly and [store the input in variables](https://docs.yellow.ai/docs/platform_concepts/studio/build/bot-variables#41-store-data-in-variables). These variables will then be used in this context.
5. Each Epic FHIR action returns a response as a JSON object or an array. [Store that response in a variable](https://docs.yellow.ai/docs/platform_concepts/studio/build/bot-variables#41-store-data-in-variables) and and to extract the required information from the payload [pass that variable](https://docs.yellow.ai/docs/platform_concepts/studio/build/bot-variables#42-retrieve-data-from-variables) in a [message node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/message-nodes1/message-nodes) to display that response to the end user.
---
## Enable Cloud features in the App Platform using App functions
# Use-cases
Now App’s developer can use the below function to execute cloud integration action node.
### Execute action node
The ```executeIntegrationAction``` function enables you to execute the action node of cloud’s Integration.
#### Sample code
```
app.executeIntegrationAction({
"integrationName": "payu-payment-gateway",
"action": "Generate Payment Link",
"dynamicParams": {
"amount": "1",
"productInfo": "testProduct",
"customerFirstName": "Test Customer",
"customerEmail": "test@test.com",
"customerMobileNumber": "9999999999",
"txnid": "123456789"
}
}).then((res)=>{
console.log("response from action node", res);
app.log(res, '||Response from action node||')
}).catch((err)=>{
console.log("Error in action node",err);
app.log(err, '||Error in action node||')
})
```
|Params’ Name|Required|Description|Example|
|--- |--- |--- |--- |
|integrationName|Mandatory|To get this value, Go to cloud.yellow.ai-> Integration -> search for require integration ->connect it using your creds-> Go to flow -> add flow for integration ->Click on integration action node -> Copy the integration name from the card-> replace first caps letter to small.|payu-payment-gateway|
|action|Mandatory|Go to flow -> click on integration card -> copy the action name from drop down|Generate Payment Link|
|dynamicParams|Mandatory|Select the action from integration card -> copy the field name as key(replace first caps letter in small) and value you can take from the user.| `{"amount":"1","productInfo":"testProduct","customerFirstName":”Test Customer","customerEmail":"test@test.com","customerMobileNumber":"9999999999","txnid": "123456789"}`|
#### Success Response
```
{
"Transaction Id": "abaac3332",
"Email Id": "test@test.com",
"Phone": "9900000000",
"Status": "Success",
"URL": "https://test.payu.in/processInvoice?invoiceId=9eec02a9e2efc335bdda2d7486121e03de24c2fa7d32d17462ad5a6a9058db"
}
```
#### Failure Response
```
{
“success”: false,
“error”: “Error processing Generate Payment Link”,
“data”:{
“success”: false,
“error”: “Error In executing action node”,
“apiResponseBody”:{
“message”:”Invalid amount”
}
}
}
```
## Configuration
1. Go to Growth then click on Data Explore, It will open cloud.yellow.ai site.
2. Go to Integration section in cloud.yellow.ai then search for your integration and connect by using your credentials.
---
## Five9
For those who use Five9 for customer support, the integration with Yellow.ai facilitates a seamless connection between your chatbot and Five9 live agents. This integration ensures a smooth transition from automated interactions to personalized support, enhancing the overall customer service experience.
## Connect Five9 with Yellow.ai
To connect your Yellow.ai account with **Five9**, follow these steps.
:::note
In a two-tier environment, you can connect an integration app in the Development environment. In a three-tier environment, you can connect the integration app either in Staging or Sandbox. All connected integrations are available in the live environment.
:::
1. On the left navigation bar, go to **Extensions** > **Integrations** > **Live chat** > **Five9**.
* This will display the Five9 integration page.
2. In **Give account name**, enter a unique name for the integration. You can use only lowercase alphanumeric characters and underscores (_).
3. In **Tenant name**: Enter the name of the tenant. To obtain this information, contact the Five9 support team.
4. In **Supervisor username**: Enter the username provided by the Five9 support team. A separate set of Five9 supervisor credentials needs to be created specifically for this integration.
5. In **Supervisor password**: Enter the password provided by the Five9 support team.
6. In **Host name**: Enter the name of the host provided by the client.
7. In **Skill ID**: Enter the Skill ID provided by the client.
8. In the **Attachment custom message** field, enter the message that will be displayed to the agent after an image is attached.
9. To customize chat headers, enable the **Customize chat headers** option. Upon enabling it, you will see the following fields:
i. **Update agent name**: Enter the agent's name.
ii. **Update agent description**: Provide a description, such as indicating that a bot icon should be updated when an agent is connected to the bot.
iii. **Update agent avatar**: Upload an avatar for the agent if you prefer not to display the agent's name.
10. Click **Connect**.
11. If you have multiple accounts, click on **+ Add account** and follow the above mentioned steps to add each of them. You can add a maximum of 15 accounts.
## Connect bot users to Five9 live agents
This integration allows you to connect with live agents on the Five9 platform directly from your Yellow.ai account.
:::note
- When multiple accounts are added, select the appropriate account for each node, allowing you to leverage the unique functionalities of each account for their intended purposes.
- During the testing process, agents should be **online** for the specific button ID or group mapped in the configuration.
:::
:::info
Use **Ticket-closed** in the **Raise Ticket node** to perform specific actions when a live chat closes, instead of using the **ticket-close** event.
:::
1. Go to **Automation** > **Build** > **Flows** > select the **Raise Ticket** node.
2. Select **Five9 Live Chat** from the **Live chat agent** drop-down list.
The following table contains the details of each field in the **Raise ticket** node.
| Field name | Sample value | Data type |Description
| -------- | -------- | -------- |-----|
|Message after ticket assignment|Requesting live agent connection.|String| The message will be displayed to the user after a ticket is successfully assigned to an agent.|
|Name| John |String|Name of the user|
|Mobile| 9870000000| String|Mobile number of the user.|
Email|test@gmail.com|String|Email address of the user.
Query|I have a concern regarding my flight ticket|String| The subject/topic/reason why the ticket was created.|
Campaign name | Chat | String | Select the campaign name that you have created. |
useBusinessHours | True or False | Boolean | Determines whether the campaign's business hours settings should be applied to customer-initiated conversations as defined in the Digital Engagement Administrator console. This parameter is set to false by default, meaning chat is always open. If set to true, chats are routed during open business hours when agents are logged in and dropped when no agents are logged in. Chat interactions received during closed business hours remain in the assigned queue for 24 hours.
disableComfortMessage | True or False | Boolean | Determines whether to prevent a chat message from being sent to a customer if the agent has not responded to a timespan defined by the administrator at the profile level. The default value of this parameter is True.
disableAutoClose | True or False | Boolean | If the auto-close feature is enabled on the Text Channels Administrator Console, the message window automatically closes when there is no response from the customer’s side for a period defined by the administrator. While using the Messaging API, the administrator can override this behavior by using the disableAutoClose parameter to prevent the conversation from closing automatically due to user inactivity. The default value of this parameter is false.
The following table contains the details of each field in the **Advanced options** section:
| Field name | Sample value | Data type | Description |
|-----------|-------|-----------|----------|
|Send chat transcript| True or False | Boolean |The Send chat transcript field allows you to send the conversation history between the end user and the bot as the initial message to the agent. Since this is a boolean field, pass the value **True** to send the chat transcript to the agent and if you don’t want to send the chat transcript to the agent, pass the value **False**. Note: In cases where the entire transcript exceeds the character limit of a single message packet in Five9, the content will be divided and sent as multiple message packets. For example, if the chat transcript contains 8000 characters and the message packet limit is 4000 characters, the transcript will be divided into two packets of 4000 characters each and sent as separate messages to the agent.|
| Custom chat transcript | Five9chat | String | Select your preferred variable to send chat transcripts in the format of your choice. Please indicate your preferred format in the variable. |
**Sample success response**
```json
"response": {
"assignedTo": true,
"success": true,
"message": "Agent is available and ticket is assigned to the agent",
"status": "ASSIGNED",
"ticketInfo": {
"id": "0191132e-5e7c-a297-bb20-60bcfbf62335",
"status": "PENDING",
"disposition": -1,
"statusCode": 202
}
}
```
**Sample failure response**
```json
"response": {
"success": false,
"assignedTo": false,
"agentNotAvailable": true,
"message": "Agent is unavailable to chat with the end user, hence transferring the control back to the bot",
"ticketInfo": {
"statusCode": 400,
"success": false,
"details": {
"response": {
"loggedInAgentsIds": [],
"activeAgentsIds": [],
"onCallAgentsIds": [],
"readyForCallAgentsIds": [],
"notReadyForCallAgentsIds": [],
"readyForVoicemailAgentsIds": [],
"readyForChatAgentsIds": [],
"readyForEmailAgentsIds": [],
"inQueueCalls": [],
"inAcdQueueVoicemails": [],
"inProgressVoicemails": [],
"inQueueCallbackCount": 0,
"vivrCallbackCount": 0,
"maxQueueDuration": 0,
"voicemailCount": 0,
"data": {
"loggedInAgentsIds": [],
"activeAgentsIds": [],
"onCallAgentsIds": [],
"readyForCallAgentsIds": [],
"notReadyForCallAgentsIds": [],
"readyForVoicemailAgentsIds": [],
"readyForChatAgentsIds": [],
"readyForEmailAgentsIds": [],
"inQueueCalls": [],
"inAcdQueueVoicemails": [],
"inProgressVoicemails": [],
"inQueueCallbackCount": 0,
"vivrCallbackCount": 0,
"maxQueueDuration": 0,
"voicemailCount": 0
},
"statusCode": 200,
"reason": "Agents are not available at the moment."
},
"stopFinalApiExecution": true
}
}
```
**Ticket close event payload**
```json
{
"event": {
"code": "ticket-closed",
"description": "This is an event that is received from five9 end when the agent closes the conversation.",
"data": {
"eventSerialNumber": 7,
"displayName": "Agilan",
"externalId": "1173875306367686869755563234",
"correlationId": "0191132e-5e7c-a297-bb20-60bcfbf62335",
"from": "USER",
"userId": 300000001875481,
"timestamp": "2024-08-02T13:03:03.713Z"
}
},
"type": "event"
}
```
---
## Freshchat
Yellow.ai’s integration with [Freshchat](https://www.freshworks.com/lp/freshchat-live-chat-software-1/?tactic_id=3419421&gclid=Cj0KCQiA_bieBhDSARIsADU4zLcCLpI23wzdYy7F2mUUk2lIuAeiAp2MGNux6yTfARuOhC8YugNFJCgaAtFZEALw_wcB#&utm_source=google-adwords&utm_medium=FChat-Search-India-Brand&utm_campaign=FChat-Search-India-Brand&utm_term=freshchat&device=c&matchtype=e&network=g&gclid=Cj0KCQiA_bieBhDSARIsADU4zLcCLpI23wzdYy7F2mUUk2lIuAeiAp2MGNux6yTfARuOhC8YugNFJCgaAtFZEALw_wcB) lets you connect with the live chat agents of Freshchat to resolve your queries.
:::note
Token has to be generated the Super Admin of the freshchat account
:::
## 1. Connect Freshchat with Yellow.ai
To connect your yellow.ai account with **Freshchat** follow these steps.
### 1.1 Fetch details from your Freshchat portal
**To retrieve App ID**
1. Login to your **Freshchat** portal as an administrator.
2. Go to **Admin Settings** > **Chat widget settings** > **Integration Settings**.
3. Under **AGENT MESSENGER** click **Copy** to copy the App ID.
**To retrieve API token**
1. Login to your **Freshchat** portal as an administrator.
2. Go to **Admin Settings** > **API Tokens**.
3. Click **Generate Token** to generate the API token and copy it.
**To retrieve API Domain**
1. Login to your **Freshchat** portal as an administrator.
2. Go to **Admin Settings** > **Channels** > **Mobile SDK**.
3. Check the data centre of the domain from the domain name under the **APP Keys** section. Data centers can belong to four regions , **India**, **USA**, **Europe** and **Australia**. In this screenshot, .in refers to **India**.
The following are the domain URLs of data centres on different regions:
1. .in - https://api.in.freshchat.com/v2
2. .eu - https://api.eu.freshchat.com/v2
3. .au - https://api.au.freshchat.com/v2 and if the domain value is just msdk.freshchat.com, then it belongs to USA data center and hence the value that needs to be configured is https://api.freshchat.com/v2
### 1.2 Enable the integration in Yellow.ai's Integration module
1. Login to cloud.yellow.ai and click **Integrations** in the module switcher.
2. Search for **Freshchat** or choose the category named **Live chat** from the left navigation bar and then click **Freshchat**.
3. Fill in the fields and click **Connect**.
4. If you have multiple accounts, follow the above mentioned steps to add each of them.
:::note
1. Enter a unique name for each account to easily identify them within the yellow.ai platform. It is recommended to use a name that aligns with its purpose for better usability.
2. You can add a maximum of 15 accounts.
3. In a two-tier environment, such as bots with only Development/Live environments, you can add account names only in the development mode. Once added and flows have been built, in the Live mode, you can only choose the account names and not edit them.
4. In a three-tier environment, such as bots with Staging/Sandbox/Production modes, in Staging and Sandbox modes, you can add and edit new accounts. However, in Production, only the account details added in Staging will be available. You can only map in the production environment.
:::
### 1.3 Configure webhook URL in Freshchat dashboard
To receive events, you need to configure the webhook URL in the **Freshchat** dashboard.
1. Login to the **Freshchat** portal as an administrator.
2. Navigate to **Admin Settings** > **Webhooks** for chat and copy the webhook URL mentioned in the **Instructions** section of the **Freshchat Integration Card** and paste it here.
## 2. Use-Case
This integration lets you connect with live agents on the **Freshchat** platform from your yellow.ai account.
:::note
When multiple accounts are added, select the appropriate account for each node, allowing you to leverage the unique functionalities of each account for their intended purposes.
:::
### 2.1 Chat with Freshchat's Live Agent
:::info
Use **Ticket-closed** in the **Raise Ticket node** to perform specific actions when a live chat closes, instead of using the **ticket-close** event.
:::
1. In the [Automation flow builder](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/raise-ticket), select the **Raise Ticket** node.
2. Select **Freshchat** from the Live chat agent drop-down list.
The following table contains the details of all the fields in the **Raise ticket** node.
| Field name | Sample value | Data type | Description |
|---------------------------|-------------------------|-----------|--------------------------------------------------------------------------------------------------|
| Message after ticket assignment | Requesting live agent connection | String | The message that will be displayed to the user after a ticket is assigned to an agent. |
| Name | Rajesh | String | Name of the end user. |
| Mobile | 9870000000 | String | Mobile number of the end user. |
| Email | test@gmail.com | String | Email address of the end user. |
| Query | I have a concern regarding my flight ticket | String | The subject/topic/reason why the ticket was created. |
| Group name | Sales | String | Freshchat group to which the ticket needs to be assigned. |
| Channel name | Chat with US | String | Freshchat topic to which the ticket needs to be assigned. |
| User ID | efgeye-fefefef-14343 | String | Freshchat userId of the user, this is passed if the previous ticket needs to be re-opened. |
| Unique Identifier | ggyugu-2343h-34343 | String | A unique identifier that will reflect as referenceId in the freshchat agent portal if passed |
| Properties | `[ { "name": "cf_test_field", "value": "test" } ]` | Array | Custom properties that can be passed while creating a ticket. Custom fields should be created in the Freschat portal , with field names beginning either with **cf_** or **cp_**. Once these fields are set up in the Freshchat portal, data should be passed in the following format: `[ { "name": "cf_test_field", "value": "test" } ]`. |
**Sample success response:**
```
{
"assignedTo": true,
"success": true,
"status": "ASSIGNED",
"ticketInfo": "{{apiresponse}}"
}
```
:::note
apiresponse represents the raw response from the Freshchat create ticket API.
:::
**Sample failure response**
```json
{
"success": false,
"assignedTo": false,
"agentNotAvailable": true,
"message": "TicketId is not created and transferring the control back to the bot",
"ticketInfo": "{{apiresponse}}"
}
```
:::note
apiresponse represents the raw response from the Freshchat create ticket API.
:::
---
## Freshdesk
The integration is tailored for users who are already using the Freshdesk platform. With Freshdesk integration, you gain the ability to seamlessly perform various support-related activities directly from the Yellow.ai Cloud platform. This includes creating and updating tickets, accessing ticket details, modifying ticket forms, retrieving agent information, creating notes, and adding watchers to tickets.
This integration enhances your support capabilities as a Freshdesk user by providing you with additional tools and functionalities within the Yellow.ai platform, facilitating a more efficient and streamlined support process.
## 1. Connect Freshdesk with Yellow.ai
For this integration, you will need **Freshdesk domain** and an **API key**.
### 1.1 Get your domain address & API Key from Freshdesk
1. Log in to your **Freshdesk** account.
2. From the browser address bar, copy the **Freshdesk domain URL**. Example: `https://yellowai-dummy.freshdesk.com`
3. Click your profile picture on the top right corner.
4. Go to the **Profile Settings**.
5. Your API Key will be available in the right corner below the *Change password* section. Copy it.
### 1.2 Add API key and domain to the Cloud platform
1. Go to the [Cloud Platform](https://cloud.yellow.ai) and navigate to the Development environment.
* In a two-tier environment, you can only add accounts in the Development environment.
* In a three-tier environment, you can only add accounts in Staging/Sandbox environment.
2. Search for **Freshdesk** in the **All Integrations** search box.
3. In **Give account name**, enter a unique name for the account.Supports only lowercase alphanumeric and underscore characters. It is recommended to use a name that aligns with its purpose for better usability.
4. Enter the **Api Key** and **Domain Name** and click the **Connect** button.
5. To connect additional accounts, repeat the steps outlined above for each account. You can add a maximum of 15 accounts.
## 2. Manage Freshdesk Tickets through Automation (bot conversations)
This integration facilitates various actions for managing Freshdesk tickets directly within Automation's bot conversations. You can view the connected accounts under Node > **Integrations** > **Freshdesk** in Automation.
:::note
When multiple accounts are added, choose the right account that you want to use to manage tickets.
:::
### 2.1 Create ticket
This action creates a new support ticket in **Freshdesk**.
**Node Input Params:**
| Field Name | Description | Datatype |
| ---------------- | ------------------------------------------------------- | --------------- |
| Email | Email address of the user. Example: jhon.doe@yellow.ai | String |
| Name | Name of the user. Example: John Doe | String |
| Phone | Mobile number of the user (sample value: 9999999999) | String |
| Priority | Priority level of the ticket (Low: 1, Medium: 2, High: 3, Urgent: 4) | Number |
| Source | Source of the ticket (Email: 1, Portal: 2, Phone: 3, Chat: 7, Feedback Widget: 9, Outbound Email: 10) | Number Type |
| Status | Status of the ticket (Open: 2, Pending: 3, Resolved: 4, Closed: 5) | Number |
| Tags | Tags associated with the ticket ("login failure", "system issue") | Array |
| Custom Fields | Custom fields and their values (`{"cf_key1": "value1", ...}`) | Object Type (Ensure key names are prefixed with "cf_") |
| Email Config ID | Email configuration ID | Number |
| Description | Description of the ticket | String |
| Group ID | Group ID associated with the ticket | Number |
| Product ID | Product ID associated with the ticket | Number |
| Subject | Subject of the ticket | String |
| Type | Type of the ticket (e.g., Incident, Problem) | String |
**Sample Response:**
```json
{
"cc_emails": [
"ram@freshdesk.com",
"diana@freshdesk.com"
],
"fwd_emails": [],
"reply_cc_emails": [
"ram@freshdesk.com",
"diana@freshdesk.com"
],
"email_config_id": null,
"group_id": null,
"priority": 1,
"requester_id": 129,
"responder_id": null,
"source": 2,
"status": 2,
"subject": "Support needed..",
"company_id": 1,
"id": 1,
"type": "Question",
"to_emails": null,
"product_id": null,
"fr_escalated": false,
"spam": false,
"urgent": false,
"is_escalated": false,
"created_at": "2015-07-09T13:08:06Z",
"updated_at": "2015-07-23T04:41:12Z",
"due_by": "2015-07-14T13:08:06Z",
"fr_due_by": "2015-07-10T13:08:06Z",
"description_text": "Some details on the issue ...",
"description": "Some details on the issue ..",
"tags": [],
"attachments": []
}
```
### 2.2 Update ticket
This action updates a single ticket.
**Node Input Params:**
| Field Name | Description | Datatype |
| ---------------- | ------------------------------------------------------- | --------------- |
| Ticket ID | Ticket identification number (e.g., 2112) | Number |
| Email | Email address of the user (e.g., jhon.doe@yellow.ai) | String |
| Name | Name of the user (e.g., John Doe) | String |
| Phone | Mobile number of the user (e.g., 9999999999) | String |
| Priority | Priority level of the ticket (Low: 1, Medium: 2, High: 3, Urgent: 4) | Number |
| Source | Source of the ticket Email: 1, Portal: 2, Phone: 3, Chat: 7, Feedback Widget: 9, Outbound Email: 10 | Number |
| Status | Status of the ticket (Open: 2, Pending: 3, Resolved: 4, Closed: 5) | Number |
| Tags | Tags associated with the ticket (e.g., ["login failure", "system issue"]) | Array |
| Custom Fields | Custom fields and their values (e.g., `{"key1": "value1", ...}`) | Object Type (Ensure key names are prefixed with "cf_") |
| Email Config ID | Email configuration ID | Number |
| Description | Description of the ticket | String |
| Group ID | Group ID associated with the ticket | Number |
| Product ID | Product ID associated with the ticket | Number |
| Subject | Subject of the ticket | String |
| Type | Type of the ticket (e.g., Incident, Problem) | String |
**Sample Response:**
```json
{
"cc_emails": [],
"fwd_emails": [],
"reply_cc_emails": [],
"description_text": "Not given.",
"description": "Not given.",
"spam": false,
"email_config_id": null,
"fr_escalated": false,
"group_id": null,
"priority": 2,
"requester_id": 1,
"responder_id": null,
"source": 3,
"status": 3,
"subject": "",
"id": 20,
"type": null,
"to_emails": null,
"product_id": null,
"attachments": [],
"is_escalated": false,
"tags": [],
"created_at": "2015-08-24T11:56:51Z",
"updated_at": "2015-08-24T11:59:05Z",
"due_by": "2015-08-27T11:30:00Z",
"fr_due_by": "2015-08-25T11:30:00Z"
}
```
### 2.3 List all tickets
This action retrieves all the tickets. By default, only 50 tickets that were created in the past 30 days will be displayed. To get more tickets, pagination parameters can be used.
**Node Input Params:**
| Field Name | Description | Datatype |
|------------|--------------------------------|--------------|
| Page No | Page number | Number |
| Page Size | Number of items per page | Number |
**Sample Response:**
````
{
"body": [
{
"cc_emails": [
"user@cc.com",
"user2@cc.com"
],
"fwd_emails": [],
"reply_cc_emails": [
"user@cc.com",
"user2@cc.com"
],
"fr_escalated": false,
"spam": false,
"email_config_id": null,
"group_id": 2,
"priority": 1,
"requester_id": 5,
"responder_id": 1,
"source": 2,
"status": 2,
"subject": "Please help",
"to_emails": null,
"product_id": null,
"id": 18,
"type": "Lead",
"created_at": "2015-08-17T12:02:50Z",
"updated_at": "2015-08-17T12:02:51Z",
"due_by": "2015-08-20T11:30:00Z",
"fr_due_by": "2015-08-18T11:30:00Z",
"is_escalated": false,
"custom_fields": {
"cf_category": "Default"
}
},
{
"cc_emails": [],
"fwd_emails": [],
"reply_cc_emails": [],
"fr_escalated": false,
"spam": false,
"email_config_id": null,
"group_id": null,
"priority": 1,
"requester_id": 1,
"responder_id": null,
"source": 2,
"status": 2,
"subject": "",
"to_emails": null,
"product_id": null,
"id": 17,
"type": null,
"created_at": "2015-08-17T12:02:06Z",
"updated_at": "2015-08-17T12:02:07Z",
"due_by": "2015-08-20T11:30:00Z",
"fr_due_by": "2015-08-18T11:30:00Z",
"is_escalated": false,
"custom_fields": {
"cf_category": null
}
}
]
}
````
### 2.4 View ticket
Retrieves the details for the specified ticket ID.
**Node Input Params:**
| Field Name | Description | Datatype |
|------------|-----------------------------------------|--------------|
| Ticket ID | Ticket identification number (e.g., 5) | Number |
**Sample Response:**
```json
{
"cc_emails": [
"user@cc.com"
],
"fwd_emails": [],
"reply_cc_emails": [
"user@cc.com"
],
"email_config_id": null,
"fr_escalated": false,
"group_id": null,
"priority": 1,
"requester_id": 1,
"responder_id": null,
"source": 2,
"spam": false,
"status": 2,
"subject": "",
"company_id": 1,
"id": 20,
"type": null,
"to_emails": null,
"product_id": null,
"created_at": "2015-08-24T11:56:51Z",
"updated_at": "2015-08-24T11:59:05Z",
"due_by": "2015-08-27T11:30:00Z",
"fr_due_by": "2015-08-25T11:30:00Z",
"is_escalated": false,
"association_type": null,
"description_text": "Not given.",
"description": "Not given.",
"custom_fields": {
"cf_category": "Primary"
},
"tags": [],
"attachments": []
}
```
### 2.5 Update multiple tickets
This action allows the user to update multiple tickets.
**Node Input Params:**
| Field Name | Description | Datatype |
|--------------------|-----------------------------------------------------------------------------------------------|---------------------|
| Ticket IDs | Array of ticket identification numbers (e.g., [5,6,7]) | Array of Number |
| Properties | Object containing ticket properties   | Object Type |
| Reply | Object containing the content of the reply to be added to the tickets  | Object Type |
| From Email | Support email address from which the reply should be sent | String |
| Email Config ID | ID of the support email configuration on the ticket | Number |
| Group ID | ID of the group to be assigned to the ticket | Number |
| Priority | Priority level of the ticket (Possible values: 1, 2, 3, 4) | Number |
| Source | Source of the ticket (Possible values: 1, 2, 3, 7, 8, 9, 10) | Number |
| Status | Status of the ticket (Possible values: 2, 3, 4, 5, 6, 7) | Number |
| Type | Type of the ticket | String |
| Product ID | ID of the product to be associated with the ticket | Number |
| Custom Fields | Key-value pairs containing the names and values of custom fields. Ensure keys are prefixed with `cf_` (e.g., `{"cf_key1": "value1", ...}`) | Object |
| Tags | Array of strings representing tags associated with the ticket | Array of strings |
| Internal Agent Id | ID of the internal agent to whom the ticket should be assigned | Number |
| Internal Group Id | ID of the internal group to which the ticket should be assigned | Number |
|Field Name| Sample Input| Remarks|
| -------- | -------- | -------- |
| Ticket IDs| [5,6,7]| Array of Number|
|Properties|| Object Type |
|Reply||Object Type Content of the reply to be added to the tickets |
|From Email |String| Support email from which the reply should be sent|
Email Config ID| Number| Support email config on the ticket. This will be used for the corresponding responses on the ticket.|
|Group ID| Number| ID of the group to be assigned on the ticket|
|Priority| Number| Used to set the priority of the ticket. Possible values are 1,2,3,4|
|Source| Number| Used to set the source of the ticket. Possible values are 1, 2,3,7,8,9,10|
|Status| Number| Used to set the status of the ticket. Possible values are 2,3,4,5,6,7|
|Type| String| Type of the ticket|
|Product ID |Number| ID of the product to be associated with the ticket|
|Custom Fields| Object| Key value pairs containing the names and values of custom fields. For custom fields, it's necessary to prefix the key with `cf_`.|
|tags| Array of strings| Tags that have been associated with the ticket|
|Internal Agent Id| Number |ID of the internal agent to whom the ticket should be assigned|
|Internal Group Id| Number| ID of the internal group to which the ticket should be assigned with|
**Sample Response:**
```
{
"job_id": "e4d18654f60b5204513155b26c6cb",
"href": "https://domain.freshdesk.com/api/v2/jobs/e4d18654f60b5204513155b26c6cb"
}
```
### 2.6 Filter tickets
This action returns a filtered list of tickets based on the specified query filter. The number of objects returned per page is 30. The total count of the results will also be returned with the result.
**Node Input Params:**
| Field Name | Description | Datatype |
| ---------- | ----------- | -------- |
| query* | Search query (e.g., "(priority:2)") | String |
| Page no | Page number (e.g., 2) | Number (Max:10) |
**Query Formats:**
* "(ticket_field:integer OR ticket_field:'string') AND ticket_field:boolean"
* "priority:>3 AND created_at:'2017-01-01'"
* "type:null AND priority:4"
**Sample Response:**
```json
{
"total": 49,
"results": [
{
"cc_emails": [
"clark.kent@kryptonspace.com"
],
"fwd_emails": [],
"reply_cc_emails": [],
"fr_escalated": false,
"spam": false,
"email_config_id": 17,
"group_id": 156,
"priority": 3,
"requester_id": 6007738334,
"responder_id": 6001263404,
"source": 2,
"company_id": 2,
"status": 2,
"subject": "Sample Title",
"to_emails": null,
"product_id": null,
"id": 47,
"type": null,
"due_by": "2016-02-23T16:00:00Z",
"fr_due_by": "2016-02-22T17:00:00Z",
"is_escalated": true,
"description": "Sample description",
"description_text": "Sample description",
"created_at": "2016-02-20T09:16:58Z",
"updated_at": "2016-02-23T16:14:57Z",
"custom_fields": {
"cf_sector_no": 7,
"cf_locked": true
}
},
{
"cc_emails": [
"bruce.wayne@gothamdomain.com"
],
"fwd_emails": [],
"reply_cc_emails": [],
"fr_escalated": true,
"spam": false,
"email_config_id": 44,
"group_id": 65,
"priority": 3,
"requester_id": 6007738334,
"responder_id": 6001263404,
"source": 2,
"company_id": 33,
"status": 2,
"subject": "New Title",
"to_emails": null,
"product_id": null,
"id": 57,
"type": null,
"due_by": "2016-02-23T16:00:00Z",
"fr_due_by": "2016-02-22T17:00:00Z",
"is_escalated": true,
"description": "New description",
"description_text": "New description",
"created_at": "2016-02-20T16:15:10Z",
"updated_at": "2016-03-14T15:58:13Z",
"custom_fields": {
"cf_sector_no": 8,
"cf_locked": true
}
}
]
}
```
### 2.7 Get all agents
Retrieves a list of all agents. The default **Page Number** is 1 and the **Page Size** is 50.
**Node Input Params:**
| Field Name | Description | Datatype |
|--------------|--------------------|--------------|
| Page Number | Page number | Number |
| Page Size | Number of items per page (max: 10) | Number |
**Sample Response:**
```json
[
{
"available": true,
"occasional": false,
"signature": null,
"id": 1,
"ticket_scope": 1,
"created_at": "2015-08-18T16:18:05Z",
"updated_at": "2015-08-18T16:18:05Z",
"available_since": null,
"type": "support_agent",
"contact": {
"active": true,
"email": "sample@freshdesk.com",
"job_title": null,
"language": "en",
"last_login_at": "2015-08-21T14:54:46+05:30",
"mobile": null,
"name": "Support",
"phone": null,
"time_zone": "Chennai",
"created_at": "2015-08-18T16:18:05Z",
"updated_at": "2015-08-25T08:50:20Z"
}
},
{
"available": true,
"occasional": false,
"signature": null,
"id": 432,
"ticket_scope": 1,
"created_at": "2015-08-28T11:47:58Z",
"updated_at": "2015-08-28T11:47:58Z",
"available_since": null,
"type": "support_agent",
"contact": {
"active": false,
"email": "superman@freshdesk.com",
"job_title": "Journalist",
"language": "en",
"last_login_at": null,
"mobile": null,
"name": "Clark Kent",
"phone": null,
"time_zone": "Chennai",
"created_at": "2015-08-28T09:08:16Z",
"updated_at": "2015-08-28T11:47:58Z"
}
}
]
```
### 2.8 Get all groups
This action returns a list of all agent groups. This data can be used in creating or updating ticket actions where a group id is required for assigning a ticket to a specific group of agents.
**Node Input Params:**
| Field Name | Description | Datatype |
|--------------|--------------------|--------------|
| Page Number | Page number | Number |
| Page Size | Number of items per page (max: 10) | Number |
**Sample Response:**
```json
[
{
"id": 6733,
"name": "Account managers",
"description": "Account managers",
"escalate_to": null,
"unassigned_for": null,
"agent_ids": [],
"created_at": "2021-02-10T07:20:31Z",
"updated_at": "2021-02-10T07:20:31Z",
"allow_agents_to_change_availability": false,
"business_calendar_id": null,
"type": "support_agent_group",
"automatic_agent_assignment": {
"enabled": false
}
},
{
"id": 6705,
"name": "Billing",
"description": "Members of the Billing team belong to this group",
"escalate_to": null,
"unassigned_for": null,
"agent_ids": [],
"created_at": "2021-02-10T06:32:10Z",
"updated_at": "2021-02-10T06:32:10Z",
"allow_agents_to_change_availability": false,
"business_calendar_id": null,
"type": "support_agent_group",
"automatic_agent_assignment": {
"enabled": false
}
},
{
"id": 6706,
"name": "Payment",
"description": "Members of the Payments team belong to this group",
"escalate_to": [
6
],
"unassigned_for": "30",
"agent_ids": [
2
],
"created_at": "2021-02-11T06:32:10Z",
"updated_at": "2021-02-11T06:32:10Z",
"allow_agents_to_change_availability": true,
"business_calendar_id": 1,
"type": "support_agent_group",
"automatic_agent_assignment": {
"enabled": true,
"type": "channel_specific",
"settings": [
{
"channel": "ticket",
"assignment_type": "skill_based_round_robin",
"assignment_type_settings": {
"capping_limit": 2
}
}
]
}
}
]
```
### 2.9 Get all email configs
Retrieves all the email configs that are configured in the support panel settings. By default, it returns 50 records. To get more data, a pagination parameter can be provided.
**Node Input Params:**
| Field Name | Description | Datatype |
|--------------|--------------------|--------------|
| Page Number | Page number | Number |
| Page Size | Number of items per page (max: 10) | Number |
**Sample Response:**
```json
[
{
"id": 1,
"name": "Primary Email",
"product_id": null,
"to_email": "support@domain.freshdesk.com",
"reply_email": "support@domain.freshdesk.com",
"group_id": null,
"primary_role": true,
"active": true,
"created_at": "2015-05-03T09:08:53+05:30",
"updated_at": "2015-05-03T09:08:53+05:30"
},
{
"id": 2,
"name": "Support emails",
"product_id": null,
"to_email": "domaincomexample@domain.freshdesk.com",
"reply_email": "example@domain.freshdesk.com",
"group_id": 2,
"primary_role": false,
"active": false,
"created_at": "2015-07-03T09:08:53+05:30",
"updated_at": "2015-07-03T09:08:53+05:30"
}
]
```
### 2.10 Get all products
Gets the list of products configured in the **Freshdesk** support panel. By default, it returns 50 records. To get more data, a pagination parameter should be provided.
**Node Input Params:**
| Field Name | Description | Datatype |
|--------------|--------------------|--------------|
| Page Number | Page number | Number |
| Page Size | Number of items per page (max: 10) | Number |
**Sample Response:**
```json
[[
{
"id": 1,
"name": "Freshservice",
"description": "Support for IT",
"created_at": "2015-07-03T09:08:53+05:30",
"updated_at": "2015-07-03T09:08:53+05:30"
}
]
```
### 2.11 Add watcher
This action adds agents as a watcher to the specified ticket.
**Node Input Params:**
| Field Name | Description | Datatype |
|------------|------------------------------------|---------------|
| Ticket ID | Ticket identification number Example: 19 | Number |
| User ID | User identification number Example: 5 | Number |
### 2.12 Get all ticket forms
Retrieves the list of all the available ticket forms from **Freshdesk**. This action doesn't require any parameter.
**Sample Response:**
```json
[
{
"id": 1,
"name": "report_an_issue",
"title": "Report an issue",
"default": true,
"description": "This form has all fields that customers can view or edit.",
"created_at": "2022-05-25T10:43:01Z",
"updated_at": "2022-06-01T10:21:34Z",
"last_updated_by": 51020877290,
"portals": []
},
{
"id": 2,
"name": "return_items",
"title": "Return items",
"default": false,
"description": "Form to raise return requests on Acme portal",
"created_at": "2022-05-27T10:33:34Z",
"updated_at": "2022-05-31T10:06:26Z",
"last_updated_by": 51020877290,
"portals": [
{
"id": 1,
"name": "portal 1"
}
]
}
]
```
### 2.13 View ticket form
Retrieves the ticket form details of the specified formId.
**Node Input Params:**
| Field Name | Description | Datatype |
|------------|-----------------------------------------|------------|
| formId | Form identification number | Number |
**Sample Response:**
```json
{
"id": 3,
"name": "return_items",
"title": "Return items",
"default": true,
"description": "Form to raise return requests on Acme portal",
"created_at": "2022-05-25T10:43:01Z",
"updated_at": "2022-06-01T10:21:34Z",
"last_updated_by": 51020877290,
"portals": [],
"fields": [
{
"id": 1,
"name": "requester",
"label": "Search a requester",
"label_for_customers": "Requester",
"position": 1,
"type": "default_requester",
"default": true,
"customers_can_edit": true,
"required_for_closure": false,
"required_for_agents": true,
"required_for_customers": true,
"displayed_to_customers": true,
"created_at": "2022-05-25 10:43:01",
"updated_at": "2022-05-25 10:43:01",
"archived": false,
"portal_cc": "false",
"portal_cc_to": "company"
},
{
"id": 2,
"name": "subject",
"label": "Subject",
"label_for_customers": "Subject",
"position": 2,
"type": "default_subject",
"default": true,
"customers_can_edit": true,
"required_for_closure": false,
"required_for_agents": true,
"required_for_customers": true,
"displayed_to_customers": true,
"created_at": "2022-05-25 10:43:01",
"updated_at": "2022-05-25 10:43:01",
"archived": false
},
{
"id": 3,
"name": "status",
"label": "Status",
"label_for_customers": "Status",
"position": 5,
"type": "default_status",
"default": true,
"customers_can_edit": false,
"required_for_closure": false,
"required_for_agents": true,
"required_for_customers": false,
"displayed_to_customers": true,
"created_at": "2022-05-25 10:43:01",
"updated_at": "2022-05-25 10:43:01",
"archived": false
}
]
}
```
### 2.14 Update ticket form
This action helps in updating the title and description of the specified formId.
**Node Input Params:**
| Field Name | Description | Datatype |
|------------|-----------------------------------------|--------------|
| formId | Form identification number | Number |
| Title | Title of the custom ticket form | String |
| Description| Description of the custom ticket form | String |
**Sample Response:**
```json
{
"id": 1,
"name": "updated_returns_form",
"title": "Updated returns form",
"default": false,
"description": "New returns form for summer sale",
"created_at": "2022-05-31T06:53:48Z",
"updated_at": "2022-06-01T14:31:25Z",
"last_updated_by": 51020877290,
"portals": [],
"fields": [
{
"id": 1,
"name": "requester",
"label": "Search a requester",
"label_for_customers": "Requester details",
"position": 1,
"type": "default_requester",
"default": true,
"customers_can_edit": true,
"required_for_closure": false,
"required_for_agents": true,
"required_for_customers": true,
"displayed_to_customers": true,
"created_at": "2022-05-31 06:53:48",
"updated_at": "2022-05-31 09:02:28",
"archived": false,
"portal_cc": "false",
"portal_cc_to": null
},
{
"id": 2,
"name": "company",
"label": "Company",
"label_for_customers": "Company",
"position": 2,
"type": "default_company",
"default": true,
"customers_can_edit": true,
"required_for_closure": false,
"required_for_agents": true,
"required_for_customers": true,
"displayed_to_customers": true,
"created_at": "2022-05-31 06:53:48",
"updated_at": "2022-05-31 06:53:48",
"archived": false
}
]
}
```
### 2.15 Update ticket form fields
This action helps in updating the fields in the ticket forms.
**Node Input Params:**
| Field Name | Description | Datatype |
|---------------------|------------------------------------------------------|---------------|
| Field ID | Field identification number | Number |
| Form ID | Form identification number | Number |
| Field Name | Name of the field | String |
| Field Placeholder | Placeholder text for the field (e.g., johndoe@yellow.ai) | String |
| Field Hint | Hint text for the field displayed in a tooltip (e.g., Customer Email) | String |
| Is Editable | Indicates if the field can be updated by customers (e.g., true) | Boolean |
| Field Position | Position of the field in the form (e.g., 2) | Number |
| Required for Customers | Indicates if the field is required for customers in the portal (e.g., false) | Boolean |
**Sample Response:**
```
{
"id": 1,
"name": "requester",
"label": "Search a requester",
"label_for_customers": "Requester email",
"position": 1,
"type": "default_requester",
"default": true,
"customers_can_edit": true,
"required_for_closure": false,
"required_for_agents": true,
"required_for_customers": true,
"displayed_to_customers": true,
"created_at": "2022-05-27 10:33:34",
"updated_at": "2022-05-31 09:25:06",
"archived": false,
"portal_cc": null,
"portal_cc_to": null,
"hint_for_customers": "Requester email",
"placeholder_for_customers": "Requester Email"
}
```
### 2.16 Create note
This action helps in creating a public or private note in the ticket.
**Node Input Params:**
| Field Name | Description | Datatype |
|---------------|-------------------------------------------------|--------------------|
| Body(HTML) | HTML content for the note (e.g., sample text) | String (HTML) |
| Ticket ID | Ticket identification number | Number |
| Notify Agents | List of email addresses to notify (e.g., ["agent1@freshdesk.com", "agent2@freshdesk.com"]) | Array of strings |
| Private | Indicates if the note is private (e.g., false for public, true for private) | Boolean |
| User ID | Identification of the agent adding the note (e.g., 3) | Number|
**Sample Response:** 5
## 3. Freshdesk node Troubleshooting guide
### Action node failed
**Error Details:**
```json
"field": "custom_fields.cf_agent",
"message": "It should be one of these values: 'Sarath,Bharath,Ajay,Prem,Senthil,Archana,Sneha Kandasamy (Freshworks),Prashanth Thiagarajan (Freshworks),Aarabhi,Srikanth,Bibin,Ibraz,Animesh,Pawan,Arivazhahan,Kirti,Abrar,Bhavana,Chitrita,Dipesh,Ashok,Nishanth,Athulya,Chandni,Waseem,Akarsh V,Mayank'",
"code": "missing_field"
```
```json
{
"field": "custom_fields.cf_category761533",
"message": "It should be one of these values: 'Transaction monitoring,Credit limit IncreaseV2,Feature Ask,App Breakages,KYC Verification Dont Use,Missing Label V2,Remittance India to US V2,Remittance U.S to India V2,ACH Transfer V2,WIRE Transfer V2,Credit card Bill Payment V2,Azpire V2,Azpire (linking to fintech Apps) V2,Azpire - Transaction Failures V2,Azpire - Transfers V2,Azpire - Bill Payments V2,Rewards 2.0 V2,Activation Journey V2,Credit card Subscription V2,SIM card request V2,Statements V2,KYC documents - Credit card / Checking account V2,Disputes V2,Card unblock V2,Card Ops V2,Account Closure V2,Bureau Reporting - Unsecured V2,Card logistics V2,Credit score tracker V2,Boost Account V2,Student Loan V2,Login/VPN issues V2,Reconciliation,ATM,CC Transaction Failures,Credit card / Debit card ( linking to fintech Apps),Junk/Influencer SPAM,Callback request'",
"code": "missing_field"
},
```
**Problem:** Ticket creation using Freshdesk keeps failing because custom fields that were configured in your Freshdesk account weren't configured/passed in the Freshdesk nodes.
**Solution:**
1. Pass the custom field names in the parameter as follows: `{"cf_key1": "value1", ...}`.
2. Ensure that you prefix 'cf_' to the key.
3. The custom field names are derived from the labels assigned to them during their creation. For instance, if you create a custom field with the label 'test', then the name of the custom field will be 'cf_test'.
This solution ensures that the required custom fields are properly configured and passed in the Freshdesk node, preventing ticket creation failures.
---
## Freshservice ITSM
Integrating Freshservice ITSM with Yellow.ai enables the following actions:
* [See list of active tickets requiring resolution](#1-see-list-of-all-tickets-list-all-tickets).
* [Check the status of a specific ticket](#2-ticket-status).
* [Create a new ticket](#3-create-ticket).
## Connecting Freshservice ITSM with your bot
In a two-tier environment, you can connect an integration app in the Development environment. In a three-tier environment, you can connect the integration app either in Staging or Sandbox. All connected integrations are available in the live environment.
To connect Freshservice ITSM, follow these steps:
1. Switch to the Development/Staging environment.
2. On the left navigation bar, click **Extensions** > **Integrations** > **ITSM** > **Freshservice ITSM**. Alternatively, you can search for the integration using the Search app.
3. **Give account name** (only lowercase alphanumeric and `_` are supported), and enter the **API Key** (This key will be provided by the client/freshservice spoc of the client), and **Domain name**.
:::note
The format of this field should be `https://yellowtest.freshservice.com/api/v2` and this is also to be provided by the client/freshservice spoc of the client.
:::
4. Click **Connect**. The integration will be enabled for the bot.
5. To add another account, repeat the above mentioned steps. You can add a maximum of 15 accounts.
## Perform Freshservice actions through Agent Conversations
Once the integration is successful, you can access the following Freshservice functions directly from the Yellow.ai bot.
:::note
When multiple accounts are added, select the appropriate account for each node, allowing you to leverage the unique functionalities of each account for their intended purposes.
:::
### 1. See List of all tickets (List all tickets)
This action retrieves User Tickets by email address.
Now the set of mandatory fields required for the successful execution of this use case (My Tickets in this case), will be displayed. The below-mentioned table below consists of the sample value, data type, and description for each field present in the above screenshot.
| Field name | Sample value | Data type | Description |
| -------- | -------- | --- | -------- |
| SortBy| desc | String | Choose whether to sort the response by ascending order (asc) of timestamp or descending order (desc) |
| UserEmail | test@gmail.com| String |Email address of the requester |
#### Sample sample response
```json
{
"ticket": {
"cc_emails": [],
"fwd_emails": [],
"reply_cc_emails": [],
"fr_escalated": false,
"spam": false,
"email_config_id": null,
"group_id": null,
"priority": 3,
"requester_id": 1000000678,
"requested_for_id": 1000000670,
"responder_id": null,
"source": 2,
"status": 2,
"subject": "Ticket Title",
"to_emails": null,
"sla_policy_id": 1000000029,
"department_id": null,
"id": 266,
"type": "Incident",
"due_by": "2017-09-08T23:03:44Z",
"fr_due_by": "2017-09-08T15:03:44Z",
"is_escalated": false,
"description": "this is a sample ticket",
"description_text": "this is a sample ticket",
"custom_fields": {
"custom_text": null,
"auto_checkbox": false
},
"created_at": "2017-09-08T11:03:44Z",
"updated_at": "2017-09-08T11:37:01Z",
"urgency": 1,
"impact": 1,
"category": null,
"sub_category": null,
"item_category": null,
"deleted": false,
"attachments": [
{
"content_type": "text/plain",
"size": 5,
"name": "attachment.txt",
"attachment_url": "https://cdn.freshservice/data/Helpdesk/attachments/production/19852343/original/attachment.txt",
"created_at": "2017-09-08T11:03:45Z",
"updated_at": "2017-09-08T11:03:45Z"
}
]
}
}
```
In case of success, you need to extract the relevant keys present in the ticket object and display them to the end user with an appropriate message with the help of any of the Message type nodes.
**To use this Integration Action Node in an app.yellow.ai bot**, then refer to the below-mentioned example:
```
app.executeIntegrationAction({
"integrationName": "fresh-service",
"action": "My Tickets",
"dynamicParams": {
"sortBy": "asc",
"userEmail": "test@gmail.com"
}
}).then((res)=>{
console.log("response from action node", res);
app.log(res, '||Response from action node||')
}).catch((err)=>{
console.log("Error in action node",err);
app.log(err, '||Error in action node||')
})
```
### 2. Ticket Status
Retrieves the current status of a specific ticket.
| Mandatory input name | Sample value | Data type | Description |
| -------- | -------- | --- | -------- |
|TicketId|1588402269|String|The ticketId whose status needs to be fetched|
#### Sample response
```json
{
"ticket": {
"cc_emails": [],
"fwd_emails": [],
"reply_cc_emails": [],
"fr_escalated": false,
"spam": false,
"email_config_id": null,
"group_id": null,
"priority": 3,
"requester_id": 1000000678,
"requested_for_id": 1000000670,
"responder_id": null,
"source": 2,
"status": 2,
"subject": "Ticket Title",
"to_emails": null,
"sla_policy_id": 1000000029,
"department_id": null,
"id": 266,
"type": "Incident",
"due_by": "2017-09-08T23:03:44Z",
"fr_due_by": "2017-09-08T15:03:44Z",
"is_escalated": false,
"description": "this is a sample ticket",
"description_text": "this is a sample ticket",
"custom_fields": {
"custom_text": null,
"auto_checkbox": false
},
"created_at": "2017-09-08T11:03:44Z",
"updated_at": "2017-09-08T11:37:01Z",
"urgency": 1,
"impact": 1,
"category": null,
"sub_category": null,
"item_category": null,
"deleted": false,
"attachments": [
{
"content_type": "text/plain",
"size": 5,
"name": "attachment.txt",
"attachment_url": "https://cdn.freshservice/data/Helpdesk/attachments/production/19852343/original/attachment.txt",
"created_at": "2017-09-08T11:03:45Z",
"updated_at": "2017-09-08T11:03:45Z"
}
]
}
}
```
**To use this Integration Action Node in an app.yellow.ai bot**, then refer to the below-mentioned example:
```json
app.executeIntegrationAction({
"integrationName": "fresh-service",
"action": "Ticket Status",
"dynamicParams": {
"ticketId": "21364"
}
}).then((res)=>{
console.log("response from action node", res);
app.log(res, '||Response from action node||')
}).catch((err)=>{
console.log("Error in action node",err);
app.log(err, '||Error in action node||')
})
```
### 3. Create Ticket
Creates a new ticket in the Freshservice ITSM app.
Now the set of mandatory fields required for the successful execution of this use case (Create Ticket in this case), will be displayed.
The below-mentioned table below consists of the sample value, data type, and description for each field present in the above screenshot.
| Mandatory input params | Sample value | Data type | Description |
| -------- | -------- | --- | -------- |
|RequesterEmailId|test@gmail.com|String|Email address of the requester. If no contact exists with this email address in Freshservice, it will be added as a new contact|
|RequesterMobileNumber|9870000000|String|Phone number of the requester. If no contact exists with this phone number in Freshservice, it will be added as a new contact|
|TicketStatus|2/3/4/5|Number|Status of the ticket|
|TicketPriority|1/2/3/4|Number|Priority of the ticket|
|TicketSource|1/2/3/4/5/6/7/8/9/10|Number|The channel through which the ticket was created|
|RequesterName|Raj|String|Name of the requester|
|TicketSubject|Test Subject|String|Subject of the ticket|
|TicketCategory|Growth|String|Category of the ticket|
|TicketSubCategory|Marketing|String|Sub-category of the ticket|
|TicketDescription|Test Description|String|HTML content of the ticket|
|CustomFields| `{custom_fields:{“this is a test”}}` |Object|Key value pairs containing the names and values of custom fields|
#### Sample response
```json
{
"ticket": {
"cc_emails": [
"ram@freshservice.com",
"diana@freshservice.com"
],
"fwd_emails": [],
"reply_cc_emails": [
"ram@freshservice.com",
"diana@freshservice.com"
],
"fr_escalated": false,
"spam": false,
"email_config_id": null,
"group_id": null,
"priority": 1,
"requester_id": 1000000675,
"requested_for_id": 1000000670,
"responder_id": null,
"source": 2,
"status": 2,
"subject": "Support Needed...",
"to_emails": null,
"department_id": null,
"id": 265,
"type": "Incident",
"due_by": "2017-09-11T10:34:28Z",
"fr_due_by": "2017-09-09T10:34:28Z",
"is_escalated": false,
"description": "Details about the issue...",
"description_text": "Details about the issue...",
"category": null,
"sub_category": null,
"item_category": null,
"custom_fields": {
"custom_text": "This is a custom text box",
"auto_checkbox": null
},
"created_at": "2017-09-08T10:34:28Z",
"updated_at": "2017-09-08T10:34:28Z",
"tags": [],
"attachments": []
}
}
```
**To use this Integration Action Node in an app.yellow.ai bot**, refer to the below-mentioned example:
```json
app.executeIntegrationAction({
"integrationName": "fresh-service",
"action": "Create Ticket",
"dynamicParams": {
"requesterEmailId": "test@gmail.com",
"requesterMobileNumber": "9870000000",
"ticketStatus": 2,
"ticketPriority": 3,
"ticketSource": 2,
"requesterName": "Raj",
"ticketSubject": “Test Subject",
"ticketCategory": “Growth",
"ticketSubCategory": “Marketing",
"ticketDescription": “Test description",
“customFields”: { "custom_text" : "This is a custom text box" }
}
}).then((res)=>{
console.log("response from action node", res);
app.log(res, '||Response from action node||')
}).catch((err)=>{
console.log("Error in action node",err);
app.log(err, '||Error in action node||')
})
```
---
## Freshteam
Yellow.ai Integration with Freshteam enables you to seamlessly access Freshteam services. With this integration, the bot can fetch employee info, create and manage time off requests, and retrieve job posting information from Freshteam.
## Integrate Freshteam with Yellow.ai
In a two-tier environment, you can connect an integration app in the Development environment. In a three-tier environment, you can connect the integration app either in Staging or Sandbox. All connected integrations are available in the live environment.
### Get your Freshteam's API key
Follow the below steps to enable Freshteam integration for your bot:
1. Login to https://www.freshworks.com/hrms/login/ and click on your Profile Avatar.
2. From the drop-down select **API key**. You can generate new API key and copy it or just copy the existing API key.
### Connect your Freshteam account to Yellow.ai
To connect to Yellow, you need your account's API key. In a two-tier environment, you can connect an integration app in the Development environment. In a three-tier environment, you can connect the integration app either in Staging or Sandbox. All connected integrations are available in the live environment.
1. Switch to the Development/Staging environment and go to **Extensions** > **Integrations** > **HR** > **Freshteam**.
2. In **Give account name**, enter a unique name for the integration. You can use only lowercase alphanumeric characters and underscores (_).
3. In **API key**, paste that API Key that you copied earlier.
4. In **Domain name**, enter your account's domain URL.
5. Click **Connect**.
6. To connect another account, click **+ Add Account** and proceed with the previous steps. You can add a maximum of 15 accounts.
---
## Accessing Freshteam Functions through bot conversations
The Freshteam integration enables bot to perform the following actions.
### 1. List all employees
List all employees integration node helps in retrieving all the employees available in Freshteam. One can retrieve employee information by applying sort and sortType filters as well.
:::note
* Only users in HR Partner, Admin, and Account Admin roles can access this API.
* When multiple accounts are added, select the appropriate account for each node, allowing you to leverage the unique functionalities of each account for their intended purposes.
:::
**Node Sample Inputs**
| Parameter | Type | Sample |
| -------- | -------- | -------- |
| Sort | String |first_name/last_name/employee_id |
| SortType | String | asc/desc |
**Return Value**
List all employee's integration node returns the value of array type, use array variable as an output variable.
### 2. Retrieve employee information
Retrieve employee information integration node helps in retrieving a particular employee based on the employee id provided.
:::note
Only users in HR Partner, Admin, and Account Admin roles can access this API.
:::
**Node Sample Inputs**
| Parameter | Type | Sample |
| -------- | -------- | -------- |
| EmployeeID | Number |5000402776 |
**Return Value**
Retrieve employee information integration node returns the value of object type, use object variable as an output variable.
### 3. List all time-off types
List all time off types integration node helps in retrieving all the time off types available in the freshteam.
:::note
Only users in HR Partner, Admin, and Account Admin roles can access this API.
:::
**Return Value**
List all time off types integration node returns the value of array type, use array variable as an output variable.
### 4. List all time off requests
List all time off requests integration node helps in retrieving all the time off requests applied by an employee based on the employee id provided.
:::note
Only users in HR Partner, Admin, and Account Admin roles can access this API.
:::
**Node Sample Inputs**
| Parameter | Type | Sample |
| -------- | -------- | -------- |
| EmployeeID | Number |5000402776 |
**Return Value**
List all time off requests integration node returns the value of array type, use array variable as an output variable.
### 5. Create a time off request
Create a time off request integration node helps in applying for leave(time off).
**Node Sample Inputs**
| Parameter | Type | Sample |
| -------- | -------- | -------- |
| StartDate | String |2022-09-19 |
| EndDate | String |2022-09-19|
| LeaveTypeID | Number |5000063084|
| Comments | String |Fever, cold, and headache|
| OptionalLeaveDays | Array |[]|
| Notify | Array |[]|
| AddToCalendar | Boolean |True|
| AutoDeclineEvents | Boolean |True|
**Return Value**
Create a time off request integration node returns the value of object type, use object variable as an output variable.
### 6. Approve a time off request
Approve a time off request integration node helps in approving a leave based on the time off id provided.
:::note
Only users in HR Partner, Admin, Reporting Manager, and Account Admin roles can access this API.
:::
**Node Sample Inputs**
| Parameter | Type | Sample |
| -------- | -------- | -------- |
| TimeoffID | Number |5000402776 |
**Return Value**
Approve a time off request integration node returns the value of object type, use object variable as an output variable.
### 7. Cancel a time off request
Cancel a time off request integration node helps in rejecting a leave based on the time off id provided.
**Node Sample Inputs**
| Parameter | Type | Sample |
| -------- | -------- | -------- |
| TimeoffID | Number |5000402776 |
**Return Value**
Cancel a time off request integration node returns the value of object type, use object variable as an output variable.
### 8. List all Job Postings
List all job postings integration node helps in retrieving all the available open jobs in an organization. One can apply an optional filter “title” for returning job information based on that title.
**Node Sample Inputs**
| Parameter | Type | Sample |
| -------- | -------- | -------- |
| Title | String |Sample Job Posting |
**Return Value**
List all time off requests integration node returns the value of array type, use array variable as an output variable.
### 9. Retrieve Job Posting information
Retrieve Job posting information integration node helps in retrieving available job information based on the job id provided.
**Node Sample Inputs**
| Parameter | Type | Sample |
| -------- | -------- | -------- |
| JobID | Number |5000402776 |
**Return Value**
Retrieve Job posting information integration node returns the value of object type, use object variable as an output variable.
**References**
* [List all employees](https://developers.freshteam.com/api/#list_all_employees)
* [Retrieve employee information](https://developers.freshteam.com/api/#retrieve_employee_information)
* [List all time off types](https://developers.freshteam.com/api/#list_all_leave_types)
* [List all time off requests](https://developers.freshteam.com/api/#list_all_leave_requests)
* [Create a time off request](https://developers.freshteam.com/api/#create_a_leave_request)
* [Approve a time off request](https://developers.freshteam.com/api/#approve_time_off)
* [Cancel a time off request](https://developers.freshteam.com/api/#cancel_time_off)
* [List all job postings](https://developers.freshteam.com/api/#list_all_job_postings)
* [Retrieve job posting information](https://developers.freshteam.com/api/#retrieve_job_posting_information)
---
## Generic oauth
Generic OAuth integration allows Yellow.ai to securely connect with various [OAuth providers](https://en.wikipedia.org/wiki/List_of_OAuth_providers) such as Google, Microsoft, Amazon, Apple, and so on. Each provider requires its own set of credentials for authentication.
By leveraging industry-standard OAuth protocols, Yellow.ai generates OAuth URLs that redirect users to the provider’s login page for secure authentication.
**Key benefits of using this integration:**
* **Multiple provider support**: Allows you to cofigure various OAuth providers like Google, Microsoft, and Amazon based on business requirements.
* **Auto-generated OAuth URL**: Simplifies the authentication process by dynamically generating OAuth URLs for secure user login.
## Integrate Generic Oauth with Yellow.ai
To integrate Generic OAuth with Yellow.ai, obtain the respective credentials. In the following procedure, we have used *Google OAuth* as an example, which requires credentials from the Google Developer Console.
### Get Google console credentials
1. Log in to the [Google developer console](https://console.cloud.google.com/).
2. Navigate to **API & Services**.
3. Go to **Credentials**.
4. Click **Create credentials** and select **OAuth Client ID**.
5. Under **Application type**, select **Web application**.
6. Enter **Authorized JavaScript origins** URL and **Authorized redirect URIs** and click **Create**.
7. Copy the **Client ID** and **Client Secret**, which is required to connect the Google OAuth provider with Yellow.ai.
* Similarly, you can obtain credentials for other OAuth providers, such as Microsoft and Amazon. For more details, refer to their respective documentation.
### Connect Generic OAuth account to Yellow.ai
You can add and manage Oauth accounts within Yellow.ai to enable authentication. You need to set up Oauth accounts when integrating various Oauth providers that require user authentication. The number of accounts you can add depends on the bot’s environment structure:
* You can add a maximum of 15 accounts.
* In a two-tier environment (Development/Live), add account names only in Development mode. After building flows, you can select existing account names in Live mode but cannot edit them.
* In a three-tier environment (Staging/Sandbox/Production), add and edit accounts in Staging and Sandbox. In Production mode, use only the accounts added in Staging and map them as needed.
To connect Generic OAuth account, follow these steps:
1. Login to the [Cloud platform](https://cloud.yellow.ai).
2. On the left navigation bar, go to **Extensions** > **Integrations** > **Tools & Utilities** > **Generic oauth**.
3. In **Give account name**, enter a unique name to identify the OAuth account.
4. Enter the Google's **Authorization URL**. For example:`https://accounts.google.com/o/oauth2/auth`. For more information, click [here](https://developers.google.com/identity/protocols/oauth2/web-server#httprest).
5. Enter the Google's **Token URL**. For example: `https://oauth2.googleapis.com/token`.
6. Paste the **Client ID** and **Client secret**, which you have copied in the Google console developer portal.
7. In **Scope**, enter the required API scope. Example: `https://www.googleapis.com/auth/userinfo.profile`
8. In **Code verifier**, enter an alphanumeric text for added security.
9. Click **Connect**.
## Enable Generic OAuth event to receive events in bot
For your bot to manage OAuth authentication events, you need to enable the `generic-OAuth-success` event. This event enables the bot to perform actions such as generating an OAuth URL and redirecting users to the login page.
To enable Generic OAuth event, follow these steps:
1. On the [Cloud platform](https://cloud.yellow.ai/), go to **Staging** or **Development** environment.
2. On the left navigation bar, click **Automation** > **Event** > **Integrations** and search for `generic-oauth-success`.
3. Click on the **more options** icon and select **Activate**. If you have connected multiple accounts, you need to enable the event for each account.
4. Once the event is activated, navigate to **Automation > Build** to create a flow.
5. Create a new flow and set **Generic OAuth Success** as the trigger event and configure action for generating an OAuth URL to redirect users to the login page.
## Generate OAuth URL link from bot conversation
To generate an OAuth URL link within a bot conversation, follow these steps:
1. Go to **Development** or **Staging** environment and navigate to **Automation** > **Build** > Select the flow where you want to generate OAuth URL link.
2. In the Automation flow builder, navigate to **Nodes** section and click **Integrations** > select **Generic oauth** node.
3. In **Account name**, select the account associated with the OAuth provider. Note that, if there are multiple accounts, you can select from which account you want to perform the action.
4. In **Action**, select **Generate Oauth URL**.
5. Select the Variable to store the response.
6. Add a Text node to display the OAuth URL stored in the selected variable.
* Preview the flow to verify that the OAuth URL is generated.
---
## Genesys Purecloud live
Yellow.ai connects with Genesys Purecloud Live, enabling users to interact with live agents. This integration helps by linking live agents from your Genesys Purecloud account with users assisted by your yellow.ai bot.
## Prerequisites
1. An active Geneysys Purecloud live account
2. An active Yellow.ai account
:::info
Only text and images are being supported from both the user and agent side.
:::
## Obtain integration credentials from Genesys Purecloud
To connect your Yellow.ai platform with Genesys Purecloud account, you need to perform the following actions in your Genesys Purecloud account to obtain the credentials to input in your Yellow.ai platform.
### Step 1: Create a user role
Create a custom role with certain scopes and assign that custom role to the user profile responsible for handling incoming chats from yellow.ai bot. To do so:
1. Go to **Admin** > **Roles/ Permissions**.
2. Click **+Add role**.
3. In **Role Details** enter a name for the role and describe it. Click **Permissions** and enable the below mentioned scopes for the role. You can search for the scopes in the highlighted search box and click **Save**.
* Messaging > Integration > All Permissions
* Conversation > Message > All Permissions
* Process Automation > Trigger > All Permissions
4. Go to **People** and click the ellipsis button beside the name of the individual for whom the role was created. Click **Edit Person**.
5. Choose **All** under **View**, enable the custom role you created in step 3 and click **Save**. By this way you assign the role to the respective person.
### Step 2: Create an OAuth client
You need to create an OAuth client to retrieve Client ID and Client secret for your Genesys login. This OAuth client is created for the role you created in the previous step.
1. Go to **Admin** > **Integrations** > **OAuth**.
2. Click **+ Add client**.
3. Enter a name for your app and choose **Client Credentials** under **Grant type**.
4. Go to **Roles** and choose the custom role you created in the previous section.
5. Click **Save**.
OAuth client gets created. Copy the **Client ID** and **Client Secret**.
### Step 3: Add Yellow.ai's webhook in Genesys
You need to create an integration to add Yellow.ai's webhook in Genesys. This helps Genesys to inform the Yellow.ai bot about user chat actions, such as drop-offs, responses, or chat endings.
1. Go to **Admin** > **Message** > **Platforms** > + **Create new integration** > **Open Messaging**.
2. Fill in the following fields:
* In **Name**, enter a name for your integration.
* In **Outbound Notification Webhook URL**, enter https://cloud.yellow.ai/ or any test URL.
:::info
A webhook is generated once the integration is established in Yellow.ai. Initially, you can provide a test URL to configure the integration. After setting it up, we'll retrieve the webhook from Yellow.ai. We will show the process in the upcoming steps.
:::
iii. In **Outbound Notification Webhook Signature Secret Token**, enter an integration ID and click **Save**.
3. Once you save, your integration ID will be generated. Copy it from the URL.
### Step 4: Add a message route
Message route helps in rotuing the messages from bot to the live agent on Genesys.
1. Create a flow in Genesys Purecloud. This flow should be based on the process the chat should reach the agent. Click [here](https://help.mypurecloud.com/articles/create-call-flow/#:~:text=Create%20an%20inbound%20call%20flow&text=The%20Create%20Flow%20dialog%20box,the%20flow's%20default%20supported%20language.) for steps.
2. After creating the flow, go to **Admin** > **Routing** > **Message Routing**.
3. Click **+** in right corner.
4. Select the flow you created in 1 and in **Addresses** select the integration you created in the previous step. Click **Save**.
## Authenticate Genesys Purecloud Live in Yellow.ai
Enter the Client ID, Client Secret and integration ID obtained from the previous sections.
1. On the [Cloud platform](https://cloud.yellow.ai), navigate to the Development/Staging environment and go to **Extensions** > **Integrations** > search for **Genesys Purecloud Live**.
2. Fill in the following fields:
* **Give account name:** enter a unique name for the integration. You can use only lowercase alphanumeric characters and underscores (_).
* **Host URL:** The URL of your genesys account.
* **Client ID:** Client obtained in [Step 2](#step-2-create-an-oauth-client).
* **Client Secret:** Client Secret obtained in [Step 2](#step-2-create-an-oauth-client).
* **Integration ID:** Integration ID obtained in [Step 3](#step-3-add-yellowais-webhook-in-genesys).
3. Click **Connect**.
4. To add another account, click **+ Add account** and proceed with the previous steps. You can add a maximum of 15 accounts.
5. Once the integration is setup, copy the Webhook URL by clicking on it.
6. Go to your **Genesys Purecloud Live account** > **Admin** > **Message** > **Platforms** > integration you created in Step 3. > **Configure**
7. Paste the copied Webhook in **Outbound Notification Webhook URL** and click **Save**.
## Configure events in Genesys Cloud for seamless agent transfer
To ensure seamless agent transfer in Genesys Cloud, you need to configure the following:
### Create Data Actions
#### chat-start
1. Navigate to **Admin** Tab > **Integrations** > **Actions**.
2. Add a new action.
3. In **Integration name**, select *Web services data actions* and enter the **Action name** as *chat-start*.
4. Go to **Setup** and select **Input Contract**.
5. Switch the format from **Simple** to **JSON** and enter the following JSON data:
```json
{
"type": "object",
"properties": {
"userId": {
"description": "Agent ID",
"type": "string"
},
"to": {
"description": "To Address",
"type": "string"
},
"conversationId": {
"description": "Conversation ID",
"type": "string"
},
"eventName": {
"description": "Event Name",
"default": "chat-start",
"type": "string"
}
},
"additionalProperties": true
}
```
6. Configure **Request URL template** as explained below:
1. Navigate to the **Configuration** section.
2. In **Request URL template**, paste the webhook URL you copied from the Yellow.ai bot.
3. Choose *POST* as the **Method**.
4. Click **Save & Publish** to apply the changes.
#### chat-end
```json
{
"type": "object",
"properties": {
"userId": {
"description": "Agent ID",
"type": "string"
},
"to": {
"description": "To Address",
"type": "string"
},
"conversationId": {
"description": "Conversation ID",
"type": "string"
},
"eventName": {
"description": "Event Name",
"default": "chat-end",
"type": "string"
},
"disconnectType": {
"description": "disconnect type",
"type": "string"
}
},
"additionalProperties": true
}
```
#### Conversation Resolved
If Genesys was previously configured for a bot, you might have an existing data flow. Create a new data action following the same steps as for **chat-start**, using the updated payload below:
```json
{
"title": "data",
"type": "object",
"required": [
"to"
],
"properties": {
"to": {
"description": "To Address",
"type": "string"
},
"conversationId": {
"description": "conversationId",
"type": "string"
},
"eventName": {
"description": "Event Name",
"default": "conversation-resolved",
"type": "string"
},
"userId": {
"description": "User ID",
"type": "string"
}
},
"additionalProperties": true
}
```
---
### Create Workflows on Genesys platform
1. On Genesys, go to **Admin** > **Architect**.
2. Hover over **Flows** and click **Workflow**.
3. Click **+ Add **and create a new workflow.
4. Navigate to the **Data** section and add three String variables - `addressTo`, `conversationId`, and `userId`.
5. In **Variable options**, select *Input to flow*.
6. Navigate back to the Initial state of your flow.
7. Add a **Call data action** node and click the arrow below the **Start** node.
8. Go to **Toolbox** > **Data** > **Call Data Action**.
9. In the **Call data action** node, select *Web Services Data Actions* from the **Category** dropdown.
10. In the **Data Action** dropdown, choose the action `chat-start` that you created earlier. Corresponding fields will be displayed.
11. In the appropriate fields, enter the variables you created earlier: `addressTo`, `conversationId`, and `userId`.
### Chat-end workflow
1. Create a new variable named *disconnectType*.
2. In the **Call data action** node for the chat end, map the disconnectType variable with the corresponding data action.
4. Map variable with data action.
#### Conversation resolved workflow
The workflow creation for the **conversation-resolved** action remains the same. Just ensure that it is correctly mapped to the appropriate data action.
Make sure to verify all variable mappings and settings to ensure everything functions as intended.
### Steps to create triggers
#### Chat-start trigger
1. Go to **Admin** > **Architect** > **Triggers**.
2. Create a new trigger named **chat-start**.
3. Choose the Topic Name as `v2.detail.events.conversation.{id}.user.start`.
4. Set the Workflow to **chat-start**.
5. Enable the trigger using the top-right corner toggle.
6. Click **Save** to store the trigger.
---
#### Chat-end trigger
1. Similar to the previous section, create a new trigger for **"chat-end."**
2. Choose the Topic Name and Workflow as shown in the screenshot below.
---
#### Conversation-resolved trigger
1. Likewise, create a new trigger for **"conversation-resolved."**
2. Choose the Topic Name and Workflow as shown in the screenshot below.
:::note
After creating all three triggers, make sure to disable any other triggers configured for the `conversation-resolved` event. This should be done immediately after setting up the new trigger for conversation resolved. If Genesys was previously configured with the Yellow.ai bot, there may be an existing trigger for "conversation resolved" that needs to be disabled.
:::
---
## Activate Genesys event in your bot
Once you connect an event, you need to enable relevant events to utilize them in the bot.
1. In Development/Staging environment, go to **Automation** > **Event** > **Integrations**.
2. Search for Genesys and click **more options** > **Activate**.
:::info
If you have added multiple accounts in your platform, enable events for each of those accounts.
:::
## Connect bot users to live agents on Genesys
:::info
Use **Ticket-closed** in the **Raise Ticket node** to perform specific actions when a live chat closes, instead of using the **ticket-close** event.
:::
1. Go to **Automation** and [build a flow](https://docs.yellow.ai/docs/platform_concepts/studio/build/Flows/journeys#2-create-a-flow) based on how you want the bot to take the user through the process.
2. Navigate to the desired point in a flow where you want to let the user talk to Genesys live agent and add the [Raise ticket node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/raise-ticket).
3. In **Live chat agent**, choose *Genesys PureCloud Live Agent*.
3. Configure the node based on the descriptions provided in the following table. The variables chosen for these fields must be previously collected in the flow via node. To know more about this in detail, click [here](https://docs.yellow.ai/docs/platform_concepts/studio/build/bot-variables#41-store-data-in-variables).
### API Field Configuration Table
| Field name | Data type | Description | Sample value |
|-----------------------------------|-----------|------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------|
| Live chat agent | - | Choose **Genesys PureCloud Live agent** in the drop-down | - |
| Account name | String | Choose the Genesys account to which the chats should be transferred | account1 |
| Message after ticket assignment | String | The message that will be displayed to the end user after a ticket is successfully assigned to an agent | Requesting live agent connection. |
| Name | String | Name of the end user | John |
| Mobile | String | Mobile number of the end user | 9800000000 |
| Email | String | Email address of the end user. This is a mandatory field | test@gmail.com |
| Query | String | The subject/topic/reason why the ticket was created | I have a concern regarding my flight ticket |
| Priority | String | The priority of the ticket | MEDIUM |
| Genesys Cloud Live Agent Custom Fields | String | Choose the variable where custom fields are stored. To include first name, last name, and nickname, use the following: | ```json { "genesysCloudUserFirstName": "Jim", "genesysCloudUserLastName": "James", "genesysCloudUserNickname": "Jam" } ``` |
| Advanced options | - | Enable this option to access advanced settings for the Genesys Live Chat integration with Bot | - |
| Send chat transcript | - | Enable this to send the conversation history between the end user and the bot to the agent. | - |
| Custom chat transcript | String | Select your preferred variable to send chat transcripts in a custom format | - |
:::note
**For `Send chat transcript`:**
If the transcript exceeds the character limit of a single Salesforce message packet, it will be split.
For example, if the limit is **4000** characters and the transcript is **8000**, it will be sent as **two separate packets** of 4000 characters each.
:::
**Result:**
**On Yellow.ai bot**
**On Genesys Purecloud Live**
#### Reference
[Document Reference](https://developer.genesys.cloud/api/digital/openmessaging/)
---
## Guide to Genesys use cases
### Close Genesys chats in sync with Yellow.ai
To end the chat in Genesys when a customer ends the chat in Yellow.ai, you need to set up a workflow.
1. Go to **Admin** > **Integrations** > **Web Services Data Actions** > **Install**. Install it and enable it.
2. Go to **Actions** > **+ Add Action** > Choose the integration enabled in the previous step.
3. Provide a name to the action and click **Add**.
4. After creating the action, go to **Setup** > **Input Contract** and paste the JSON given below the image.
```json
{
"title": "data",
"type": "object",
"required": [
"to",
"disconnectType"
],
"properties": {
"to": {
"description": "To Address",
"type": "string"
},
"disconnectType": {
"description": "The type of disconnection",
"type": "string"
},
"conversationId": {
"description": "conversationId",
"type": "string"
},
"eventName": {
"description": "Event Name",
"default": "conversation-resolved",
"type": "string"
}
},
"additionalProperties": true
}
```
5. Go to **Configuration**, in **Request URL Template**, paste the webhook URL(copied from Yellow.ai bot) and select the method as POST. After this, click **Save & Publish**.
6. Go to **Admin** > **Architect**. Hover over **Flows** and click **Workflow**.
7. Click **+ Add** and create a new workflow.
8. Add three String variables. To add a variable go to **Data** > enter a name for the variable and click **Create**.
9. Click the variable to add details.
Enable **Input to flow** in each variable and pass an initial value for the variable which disconnects the chat when the user ends it.
10. Go back to **Initial state** and below the **Start node**, add a **Call Data Action** node. To do so, click the arrow below **Start node** and go to **Toolbox** > **Data** > **Call Data Action**.
11. Once you add the node, in **Category** select **Web Services Data Actions** and in **Data Action** select the action you created in step 3.
12. Once you select the action, corresponding fields will display. Pass the variables you created in step 8.
13. Click **Save** to save your settings, and then click **Publish**.
:::info
Make sure to keep the workflow ID found in the URL handy, as it will be necessary to access the API.
:::
### Wrap-up code-based ticket closure (Recommended)
To ensure that tickets are closed based on the wrap-up code instead of the "End Conversation" action taken by the agent, add the following conditions into the chat-end event, as shown in the screenshot below.
### Issue arising when not using wrap-up code-based ticket closure
If you're not using wrap-up code-based ticket closure with Genesys, you might encounter issues when an agent ends the conversation by clicking the "End Conversation" button or declines the conversation when prompted. In these cases, we receive the same data from Genesys, which signals our system to end the conversation on the bot for the user. However, we can't distinguish whether the agent is closing the ticket or declining it. This confusion can also occur when an agent transfers the conversation to a queue, and another agent declines the ticket.
We recommend using wrap-up code-based ticket closure for smoother ticket management.
---
## Genesys Live Chat
Yellow.ai Integration with Genesys Live Chat allows you to seamlessly connect your genesys service with the yellow.ai platform.
:::note
We recommend this integration if you are using Genesys on-prem solution otherwise you should use [Genesys PureCloud](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/genesys-cloud-livechat) integration as that would be the latest version from Genesys.
:::
## Integrating Genesys Live Chat
1. In Development/Staging environment, go to **Extensions** > **Integrations** > **Live chat** > **Genesys Connect Live Chat**.
2. In **Give account name**, enter a unique name for the integration. You can use only lowercase alphanumeric characters and underscores (_).
3. Configure the other details based on the description provided in the following table:
Option | Description
------ | -----------
Genesys host | The host address for the Genesys Live Chat service. It typically includes the URL or IP address where the service is hosted.
Service name | The name of the Genesys Live Chat service that your integration will connect to.
Send attachment as link | Choose *Enable* to send attachments sent during the chat as links; keep it *Disabled* to directly embed them in the chat interface.
Insecure Connection | Enable this option to allow the integration to establish connections with the Genesys Live Chat service using insecure protocols such as HTTP. Disabling it ensures that only secure connections (HTTPS) are permitted (default option).
Agent inactivity | Choose whether the system to monitor agent activity during the chat session. Enabling it lets you monitor, while disabling it means no tracking of agent activity.
Agent inactivity timeout (in milliseconds) | If agent inactivity monitoring is enabled, this setting specifies the duration of inactivity (in milliseconds) after which the system will consider an agent as inactive.
Customise chat headers | This allows you to customize the headers displayed within the chat interface. Enable it to personalize the appearance of the chat window or to include specific information relevant to your organization or branding. Customize the header using the following options.
Update agent name | Update or customize the name displayed for the agent in the chat interface.
Update agent description | Customize the description associated with the agent in the chat interface.
Update agent avatar | Update the avatar or profile picture associated with the agent in the chat interface.
4. Click **Connect**.
5. To add another account, click **+ Add account** and follow the above mentioned steps to add each of them. You can add a maximum of 15 accounts.
## Add Genesys Live Chat to bot conversation
You can use **Raise ticket** node to create a conversation with Genesys agent and once conversation initiates the user can talk to the agent.
In the **Automation** > **Build**, to add a node where you want to integrate Genesys Live Chat, follow these steps:
1. Navigate to the desired point in a flow where you want to add the Genesys Live Chat node.
2. Add a new node and select **Integrations** > **Raise Ticket**. You will see Raise ticket configuration screen.
3. In **Live chat agent**, choose *Genesys live chat*.
4. Configure other necessary details.
:::info
Use **Ticket-closed** in the **Raise Ticket node** to perform specific actions when a live chat closes, instead of using the **ticket-close** event.
:::
## Limitations
- In this integration, only text messages from both sides are supported.
## Reference
[API Documentation](https://docs.genesys.com/Documentation/GMS/latest/API/ChatAPIv2)
---
## Google Calendar
## Scope of Integration
Yellow.ai Integration with Google Calendar enables you to seamlessly access google calendar services. Any customer who has a google account will be able to connect with yellow.ai using OAuth. Using this integration you can create, read events and also you can search for the busy time slots of the person and this can help you to create events according to it.
## Configuration
Configuring the integration with Google calendar is straightforward. Follow the steps defined below to start integrating:
### Navigate to integrations tab
Inside your project, navigate to the integrations tab and then from the left side bar select Tools & Utilities, You will find Google Calendar.
### Connect your google account
Click on **Sign in with Google**. After you click that, you will notice that you will be prompted to login to your google account, once you provide your login credentials, you have to click on **Allow** in the consent screen.
Following the above steps will connect your Google calendar with yellow.ai platform.
If you have multiple accounts, follow the above mentioned steps to add each of them.
:::note
1. Enter a unique name for each account to easily identify them within the yellow.ai platform. It is recommended to use a name that aligns with its purpose for better usability.
2. You can add a maximum of 15 accounts.
3. In a two-tier environment, such as bots with only Development/Live environments, you can add account names only in the development mode. Once added and flows have been built, in the Live mode, you can only choose the account names and not edit them.
4. In a three-tier environment, such as bots with Staging/Sandbox/Production modes, in Staging and Sandbox modes, you can add and edit new accounts. However, in Production, only the account details added in Staging will be available. You can only map in the production environment.
:::
## Use-cases
Following are the use-cases which are currently accommodated in the Integration:
:::note
When multiple accounts are added, select the appropriate account for each node, allowing you to leverage the unique functionalities of each account for their intended purposes.
:::
### Simple integration with Oauth
Google calendar integration with yellow.ai happens through the Oauth 2.0 approach.
While integrating, yellow.ai navigates the user to the login page of Google, user has to login into his google account and has to provide his consent to access his calendar data.
### Do actions with google calendar action nodes
You can create a new calendar event by specifying the timings, event title, description etc.. You can check the time slots of the person where you get busy time slots of the person and can create the event accordingly.
You can also read the calendar event with the event id to get the updates of that event.
For more information about action nodes you use here, refer this [doc](https://developers.google.com/calendar/api/v3/reference/events/)
:::note
Limitations of the current integration with Google Calendar is that only event creation is supported and not editing.
When an event is created using the **create event action node**, the *eventID* can be found in the response (payload) of that action node.
:::
---
## Google Sheets
Google Sheets integration enables your AI Agent to seamlessly access Google sheets services. You can use OAuth to connect your Google account with yellow.ai using OAuth. Using this integration you can create, read, insert/update and clear values from a spreadsheet.
## Configuration
Configuring the integration with Google sheets is straightforward. Follow the steps defined below to start integrating:
### Navigate to integration tab:-
Inside your project, fom the switcher navigate to the Integrations, search for Google Sheets in the search bar, or you can find Google Sheets under Tools & Utilities section.
### Connect your google account:-
One can easily enable Google sheets integration for their bot using Oauth. Follow the below steps to enable Google Sheets integration for your bot:-
1. Click on `Sign in with Google` button.
2. Login with your Google credentials in the window opened.
3. Click on `Allow Access` to provide your bot the access to Google Sheets.
Following the above steps will connect your Google Sheets with Yellow.ai platform.
If you have multiple accounts, follow the above mentioned steps to add each of them.
:::note
1. Enter a unique name for each account to easily identify them within the yellow.ai platform. It is recommended to use a name that aligns with its purpose for better usability.
2. You can add a maximum of 15 accounts.
3. In a two-tier environment, such as bots with only Development/Live environments, you can add account names only in the development mode. Once added and flows have been built, in the Live mode, you can only choose the account names and not edit them.
4. In a three-tier environment, such as bots with Staging/Sandbox/Production modes, in Staging and Sandbox modes, you can add and edit new accounts. However, in Production, only the account details added in Staging will be available. You can only map in the production environment.
:::
## Use-cases
Following are the use-cases which are currently accommodated in the Integration:
:::note
When multiple accounts are added, select the appropriate account for each node, allowing you to leverage the unique functionalities of each account for their intended purposes.
:::
### CreateSpreadsheet:-
Create spreadsheet integration node helps user in creating a Google spreadsheet using the spreadsheet name and the sheet names provided by the user. These created spreadsheets can be found in user’s Google sheets account with which the integration is enabled.
#### Node Sample Inputs:-
Parameter
Type
Sample
title
string
Demo Sheet
sheets
array
```json
[
{
"properties": {
"title": "Sheet 1 name"
}
},
{
"properties": {
"title": "Sheet 2 name"
}
}
]
```
### GetValuesFromSheet:-
Get values from sheet integration node helps user in retrieving values from sheet. Based on the Spreadsheet ID, Ranges and Major Dimension it will return the values.
#### Node Sample Inputs:-
Parameter
Type
Sample
majorDimension
string
ROWS(or)COLUMNS
ranges
string
Sheet1!A1:B2
spreadSheetID
string
1fExJP4rbjNKpbSHySJl4kOjwJ-mGUUzzsCs_qrC0YgI
### Insert/UpdateValuesInSheet:-
Insert/Update Values in Sheet integration node helps user in inserting or updating values in a sheet. This node inserts/updates the values in a spreadsheet in the specified range with provided values.
#### Node Sample Inputs:-
Parameter
Type
Sample
majorDimension
string
ROWS(or)COLUMNS
range
string
Sheet1!A1:B3
values
array
{`[
[1, 2, 3],
[4, 5, 6]
]`}
spreadSheetID
string
1fExJP4rbjNKpbSHySJl4kOjwJ-mGUUzzsCs_qrC0YgI
### ClearValuesInSheet:-
Clear values in a sheet integration node helps users in clearing values in a spreadsheet using the Spreadsheet ID and the Range provided by the user.
#### Node Sample Inputs:-
Parameter
Type
Sample
ranges
array
["Sheet1!A1:B3","Sheet1!A4:B6"]
spreadSheetID
string
1fExJP4rbjNKpbSHySJl4kOjwJ-mGUUzzsCs_qrC0YgI
## References:-
1. [Create a Spreadsheet](https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/create)
2. [Get Values from a Sheet](https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets.values/batchGet)
3. [Insert/Update Values in a Sheet](https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets.values/batchUpdate)
4. [Clear Values in a Sheet](https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets.values/batchClear)
---
## OpenAI GPT-3 integration (Beta)
Yellow.ai platform can be integrated with [OpenAI GPT-3](https://openai.com/blog/gpt-3-apps). We currently support DaVinci, Curie, Babbage, and custom language models.
:::note
The GPT-3 integration is currently in beta, so there may be issues or limitations while it's being tested and refined..
:::
#### What is OpenAI GPT-3?
OpenAI GPT-3 is an advanced artificial intelligence language model developed by OpenAI, with a capacity of 175 billion parameters. It uses deep learning techniques to generate natural language text and has been pre-trained on a massive amount of data from the internet and other sources. The OpenAI GPT-3 is used for language translation, chatbots, writing assistance, and content generation, and is known for its ability to generate human-like text with remarkable accuracy.
#### How does a OpenAI GPT-3 chatbot work?
The chatbot can be designed to receive input from users which is then sent to GPT-3 for processing.
OpenAI GPT-3 will use its pre-trained knowledge to generate a response based on the user's input, which is then sent back to the chatbot. The chatbot displays the generated response to the user in a natural and coherent way.
## 1. Build a chatbot using GPT-3
To build a chatbot using OpenAI GPT-3, you need to connect your open AI account with your yellow.ai platform. To do so, follow these steps:
### 1.1 Retrieve the OpenAI API key
1. Log in to your [OpenAI](https://auth0.openai.com/u/signup/identifier?state=hKFo2SBYQVNnbUlSUDNBaUdUTERlWnZUUk1abDF0SEpaeGROa6Fur3VuaXZlcnNhbC1sb2dpbqN0aWTZIGZsTThtY1liTGE4S3BEanVzOGtVUTYtd3MycXkzR20to2NpZNkgRFJpdnNubTJNdTQyVDNLT3BxZHR3QjNOWXZpSFl6d0Q) website.
2. Click your profile picture on the top right corner and click **View API keys**.
3. Click the **+Create new secret key** button to generate a new API key.
### 1.2 Retrieve the organization key(ID)
If you are a part of or have more than one organization, you have to configure an organization key. Follow these steps to retrieve the organization key:
1. Click on your profile picture on the top right corner and click **Manage account**.
2. Click **Settings** on the left sidebar and copy the **Organization ID**.
### 1.3 Enable GPT-3 on yellow.ai
1. Go to cloud.yellow.ai and click on **Integrations** in the module switcher.
2. Search for **GPT-3** in the search box.
3. Enter the **API key** and **Organization Key** (retrieved in the previous steps) and click **Connect**.
:::note
API usage will depend on your org subscription.
:::
## 2. Use-cases
The following use case is currently supported in this integration:
### 2.1 Generate answers using OpenAI GPT-3
Your chatbot users can receive answers to their queries by leveraging the GPT-3 text completion model. We support Da Vinci, Curie, Babbage, Ada, and custom models. By selecting one of these models, your chatbot can provide detailed and precise responses from GPT-3.
:::info
If you want your chatbot to provide accurate answers for a specific use case, such as if you run a car shop and want your bot to answer questions about your services and pricing, then you can choose to create a custom model. By training your model on OpenAI and connecting it to your yellow.ai platform, you can tailor your chatbot to your specific needs.
:::
1. In the Automation flow builder, go to **Integrations** > **GPT-3**.
2. Fill in the fields based on the details provided in the following table.
**Node Input Params:**
| Field Name | Sample Input | Data Type |Remarks|
| -------- | -------- | -------- |--------|
| Model | text-davinci-003 | String |The model based on which the answers will be genrated.|
|Query|Suggest a tag line for an ice cream shop|String Type|User query|
|Max Words (optional)|50|String | It is recommended to keep it to 100 words or less.|
|Prediction Risk(optional)|0.5|Number|This feature allows you to control the confidence level at which the model predicts answers.|
**Sample Response:**
```js
{
"id": "cmpl-6ktdmH8VoyYh1dJRxwa2WIDaW49I6",
"object": "text_completion",
"created": 1676634990,
"model": "text-davinci-003",
"choices": [
{
"text": "\n\nYou asked, \"What is the best way to learn a new language?\"",
"index": 0,
"logprobs": null,
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 4,
"completion_tokens": 17,
"total_tokens": 21
}
}
```
---
## Hubspot CRM
The HubSpot CRM integration enables direct management of your HubSpot CRM account through yellow.ai's bot. This integration allows effortless creation, retrieval, updating, deletion, and searching for contacts in your HubSpot CRM account directly from the bot interface.
## Supported Hubspot CRM actions in Yellow.ai
Once the integration is established, you can perform the following HubSpot CRM actions directly from the bot interface.
| Action | Description |
|--------- | -----------|
| Create a contact | Creates a new contact |
| Get a contact | Fetches a particular contact |
| Delete a contact | Deletes a contact |
| Update a contact| Modifies details of a particular contact |
| Search a contact by phone| Looks for a contact using phone number |
| Search a contact by email| Looks for a contact using email address |
## Connect Hubspot CRM with Yellow.ai
**Prerequsites:**
1. An active Hubspot CRM account
2. An active yellow.ai account.
To connect your Hubspot CRM account with Yellow.ai, follow the these steps:
1. On the left navigation bar, go to **Extensions** > **Integrations** > **CRM** > **Hubspot**. Alternatively, you can use the Search box to find the integration app.
2. In **Give account name** give a unique name to your Hubspot CRM account and click **Connect**.
:::info
1. In a two-tier environment, add account names in Development and use them in Live.
2. In a three-tier environment, add accounts in Staging and Sandbox, and they'll be available in Production.
:::
3. Sign in to your **Hubspot CRM** account when prompted. From there, select the Hubspot CRM account you want to link with Yellow.ai and click **Choose Account** to authorize Yellow.ai to access **Hubspot CRM**.
4. You can add up to 15 accounts. To add another Hubspot CRM account, click on **Add account** and follow the steps mentioned above.
## Enable events for Hubspot CRM actions
For the bot to perform certain actions when an event occurs in Hubspot CRM, the event needs to be activated.
The following are the events available for Hubspot in Yellow.ai:
| Event | Description |
| -------------------------- | ----------------------------------------- |
| hubspot-contact-created | Contact is created in Hubspot |
| hubspot-contact-changed | Contact is modified in Hubspot |
| hubspot-contact-deleted | Contact is deleted in Hubspot |
| hubspot-contact-merged | Contacts are merged in Hubspot |
| hubspot-contact-restored | Contact is restored in Hubspot |
### Add webhook to receive events
You need to add the webhook URL from the integration page in your Hubspot CRM app to receive the events mentioned above. To do so:
1. Go to **Hubspot CRM integration** and copy the Webhook URL.
2. Go to your **Hubspot CRM** account and click the **Settings** icon.
3. Go to **Integrations** > **Private Apps** and click **Create a private app**.
4. In **Basic Info**, enter a **Name** and **Description**. You can also upload a logo for that app if required.
5. Go to **Scopes**, and enable the scopes for the actions for which you wish to recieve events from Hubspot.
6. Go to **Webhooks** and past the Webhook URL copied in step 1. then, click **Create Subscription** to create the app.
7. In the following screen, select the object types and the events you'd like to get notified. Then, click **Subscribe**.
8. Click **Create app** on the top right corner.
### Activate events in Yellow.ai
To activate an event and use it in your flow,
1. Go to **Event** > **Integrations** and search for Hubspot events and click **Activate** next to the respective event.
3. Go to a flow and include that event in the Start node and [build the flow](https://docs.yellow.ai/docs/platform_concepts/studio/build/Flows/journeys#2-create-a-flow) to carry out the action when that event occurs.
## Manage Hubspot CRM via Yellow.ai AI agent
To manage your Hubspot CRM account through yellow.ai bot, follow these steps:
1. Go to **Automation** and [create a flow](https://docs.yellow.ai/docs/platform_concepts/studio/build/Flows/journeys#2-create-a-flow) based on your requirement.
2. In whichever point you want the bot to access Hubspot CRM, inlcude the Hubspot CRM node. For that, drag the node connector, go to **Integrations** > **Hubspot**.
3. Configure the **Hubspot CRM** node based on the descriptions provided in the following:
* **Account name:** Choose the Hubspot CRM account.
* **Action:** Choose the [action](#supported-hubspot-crm-actions-in-yellowai) to be performed.
* Depending on the selected object, the corresponding fields will be shown. To fill those fields, you need to collect it as an input from users beforehand. Construct the flow accordingly and [store the data in variables](https://docs.yellow.ai/docs/platform_concepts/studio/build/bot-variables#41-store-data-in-variables). These variables will then be passed in those fields.
4. Each Hubspot CRM action returns a response as a JSON object. [Store that response in a variable](https://docs.yellow.ai/docs/platform_concepts/studio/build/bot-variables#41-store-data-in-variables) and [pass that variable](https://docs.yellow.ai/docs/platform_concepts/studio/build/bot-variables#42-retrieve-data-from-variables) in a [message node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/message-nodes1/message-nodes) to display that response to the end user.
For example, if you receive the following response, you can use this syntax ``` {{{variables.variablename.results.0.properties.lastname}}} ``` to filter out the contact's last name.
```
{
"total": 0,
"results": [
{
"createdAt": "2019-10-30T03:30:17.883Z",
"archived": false,
"id": "512",
"properties": {
"company": "Biglytics",
"createdate": "2019-10-30T03:30:17.883Z",
"email": "bcooper@biglytics.net",
"firstname": "Bryan",
"lastmodifieddate": "2019-12-07T16:50:06.678Z",
"lastname": "Cooper",
"phone": "(877) 929-0687",
"website": "biglytics.net"
},
"updatedAt": "2019-12-07T16:50:06.678Z"
}
],
"paging": {
"next": {
"link": "?after=NTI1Cg%3D%3D",
"after": "NTI1Cg%3D%3D"
}
}
}
```
-----
### Create a contact
1. In the Automation flow builder, select the **Integrations** node and click **Hubspot** from the list of integrations that have been enabled for that AI agent.
2. After clicking **Hubspot**, an **Integration Action Node** will be added to the flow builder. When you click that node, you will see all use cases of this integration in a drop-down. Choose **Get contact**, choose **Create a contact** action.
2. Fill in all the mandatory fields. The below-mentioned table consists of the sample value, data type, and description for all these fields.
| Field name | Sample value| Data type |Description |
| -------- | -------- | -------- |----|
First name | John | String | Provide the fist name of the contact.
Company | Yellow.ai | String | Provide name of the contact's company.
Email | john@gmail.com | String | Provide email ID of the user
Last name | Smith | String | Provide the fist name of the user.
Phone | 9980055678 | String | Provide the phone number of the user.
Website | `https://www.yellow.ai` | String | Provide contact's company website.
**Sample success response**
```json
{
"id": "166055775073",
"properties": {
"createdate": "2025-10-22T08:15:12.069Z",
"email": "dwij@test.com",
"firstname": "Dwij",
"hs_all_contact_vids": "166055775073",
"hs_associated_target_accounts": "0",
"hs_currently_enrolled_in_prospecting_agent": "false",
"hs_email_domain": "test.com",
"hs_full_name_or_email": "Dwij",
"hs_is_contact": "true",
"hs_is_unworked": "true",
"hs_lifecyclestage_lead_date": "1761120912069",
"hs_membership_has_accessed_private_content": "0",
"hs_object_id": "166055775073",
"hs_object_source": "INTEGRATION",
"hs_object_source_id": "370598",
"hs_object_source_label": "INTEGRATION",
"hs_pipeline": "contacts-lifecycle-pipeline",
"hs_prospecting_agent_actively_enrolled_count": "0",
"hs_prospecting_agent_total_enrolled_count": "0",
"hs_registered_member": "0",
"hs_sequences_actively_enrolled_count": "0",
"lastmodifieddate": "2025-10-22T08:15:12.069Z",
"lifecyclestage": "lead",
"num_notes": "0"
},
"createdAt": "2025-10-22T08:15:12.069Z",
"updatedAt": "2025-10-22T08:15:12.069Z",
"archived": false,
"url": "app.hubspot.com/go-to/44273183/0-1/166055775073"
}
```
**A sample screenshot**
-----
### Get a contact
1. In the **Hubspot** integration action node, choose **Get a contact**.
2. Fill in all the mandatory fields. The below-mentioned table consists of the sample value, data type, and description for all these fields.
| Field name | Sample value| Data type |Description |
| -------- | -------- | -------- |----|
Contact ID | 166055775073 | string | Provide the unique contact ID of the user to fetch their details.
**Sample Success Response**
```json
{
"id": "166055775073",
"properties": {
"createdate": "2025-10-22T08:15:12.069Z",
"email": "dwij@test.com",
"firstname": "Dwij",
"hs_object_id": "166055775073",
"lastmodifieddate": "2025-10-22T08:15:20.886Z",
"lastname": null
},
"createdAt": "2025-10-22T08:15:12.069Z",
"updatedAt": "2025-10-22T08:15:20.886Z",
"archived": false,
"url": "app.hubspot.com/go-to/44273183/0-1/166055775073"
}
```
**A sample screenshot of Get contact:**
----
### Delete a contact
1. In the **Hubspot** integration action node, choose **Delete a contact** action.
2. Fill in all the mandatory fields. The below-mentioned table consists of the sample value, data type, and description for all these fields.
| Field name | Sample value| Data type |Description |
| -------- | -------- | -------- |----|
Contact ID | 166055775073 | string | Provide the unique contact ID of the user to delete their details.
----
### Update a contact
1. In the **Hubspot** integration action node, choose **Update a contact** action.
2. Fill in all the mandatory fields. The below-mentioned table consists of the sample value, data type, and description for all these fields.
| Field name | Sample value| Data type |Description |
| -------- | -------- | -------- |----|
Contact ID | 166055775073 | string | Provide the unique contact ID of the contact to update their details.
First name | John | String | Provide the fist name of the contact.
Company | Yellow.ai | String | Provide name of the contact's company.
Email | john@gmail.com | String |
Last name | Smith | String | Provide the fist name of the contact.
Phone | 9980055678 | String | Provide the phone number of the contact.
Website | `https://www.yellow.ai` | String | Provide contact's company website.
**Sample success response**
```json
{
"id": "166055775073",
"properties": {
"createdate": "2025-10-22T08:15:12.069Z",
"firstname": "Dwij",
"hs_is_contact": "true",
"hs_is_unworked": "true",
"hs_object_id": "166055775073",
"hs_object_source": "INTEGRATION",
"hs_object_source_id": "370598",
"hs_object_source_label": "INTEGRATION",
"hs_pipeline": "contacts-lifecycle-pipeline",
"hs_searchable_calculated_phone_number": "9678452348",
"lastmodifieddate": "2025-10-22T08:25:04.424Z",
"lifecyclestage": "lead",
"phone": "9678452348"
},
"createdAt": "2025-10-22T08:15:12.069Z",
"updatedAt": "2025-10-22T08:25:04.424Z",
"archived": false,
"url": "app.hubspot.com/go-to/44273183/0-1/166055775073"
}
```
**A sample screenshot**
-----
### Search a contact by phone
1. In the **Hubspot** integration action node, choose **Search a contact by phone** action.
2. Fill in all the mandatory fields. The below-mentioned table consists of the sample value, data type, and description for all these fields.
| Field name | Sample value| Data type |Description |
| -------- | -------- | -------- |----|
Phone | 9987765434 | String | Provide the phone number of the contact to search their details.
**Sample Success Response**
```json
{
"total": 1,
"results": [
{
"id": "166055775073",
"properties": {
"createdate": "2025-10-22T08:15:12.069Z",
"email": "dwij@test.com",
"firstname": "Dwij",
"hs_object_id": "166055775073",
"lastmodifieddate": "2025-10-22T08:25:04.424Z",
"lastname": null
},
"createdAt": "2025-10-22T08:15:12.069Z",
"updatedAt": "2025-10-22T08:25:04.424Z",
"archived": false
}
]
}
```
**A sample screenshot:**
----
### Search a contact by email
1. In the **Hubspot** integration action node, choose **Search a contact by email** action.
2. Fill in all the mandatory fields. The below-mentioned table consists of the sample value, data type, and description for all these fields.
| Field name | Sample value| Data type |Description |
| -------- | -------- | -------- |----|
Email | john@gmail.com | String | Provide the email ID of the contact to search their details.
**Sample Success Response**
```json
{
"total": 1,
"results": [
{
"id": "166055775073",
"properties": {
"createdate": "2025-10-22T08:15:12.069Z",
"email": "dwij@test.com",
"firstname": "Dwij",
"hs_object_id": "166055775073",
"lastmodifieddate": "2025-10-22T08:15:20.886Z",
"lastname": null
},
"createdAt": "2025-10-22T08:15:12.069Z",
"updatedAt": "2025-10-22T08:15:20.886Z",
"archived": false
}
]
}
```
**A sample screenshot:**
---
## Google identity management
Integrate your yellow.ai platform with Google Identity management for a simplified user authentication and enhanced security. This integration lets you effortlessly create a login URL within the Yellow.ai platform. This URL allows users to conveniently log in and access their information, ensuring a smooth and efficient experience.
## Connect Google identity management with Yellow.ai.
To integrate your Google Identity Management account with Yellow.ai, follow these steps:
### Fetch Client ID and Client Secret from Google console
1. Go to Google's [developer portal](https://developers.google.com/) and [create a new project](https://console.cloud.google.com/projectcreate).
2. Fill in the details and click **Create**.
3. Click more on the top right corner and click **APIs & Services** > **Enabled APIs & services**.
4. To set up the OAuth, click **Configure consent screen** on the right.
5. Choose the **User Type** as **Internal** and click **Create**.
6. Fill in all the mandatory fields in the following page and click **Save and Create** at the bottom of the page.
7. Set the scopes in the following screen. Click [here](https://developers.google.com/identity/protocols/oauth2/scopes) to know about the scopes in detail.
8. Go to **+ Create Credentials** > **OAuth client ID**.
9. Copy the **Client ID** and **Client Secret**.
:::info
To retrieve package name and private key from google console, please follow the steps mentioned [here](https://www.iwantanelephant.com/blog/2020/11/17/how-to-configure-api-access-to-google-play-console/).
:::
### Add the credentials in Yellow.ai
1. Go to **Integrations** > Search for **Google Identity Management**.
2. Fill in the following fields:
* **Give account name**: Provide a name to your account.
* **Client ID**: Paste the Client ID. (copied from the previous step)
* **Client secret**: Paste the Client secret. (copied from the previous step)
3. Click **Connect**.
4. After a successful integration, copy the Webhook URL.
5. Go to your **Google console** > **APIs & Services** > **Credentials** and paste it under **Authorized redirect URIs**.
## Activate Google auth success event
To let the yellow.ai bot know that the user has successfully logged in, you need to activate this event.
1. Go to **Automation** > **Event** > **Integration** > Search for google-auth-success > **Activate**.
2. You can set this event as a [start trigger for a flow](https://docs.yellow.ai/docs/platform_concepts/studio/build/Flows/configureflow#trigger-flow-using-event). This flow will get triggered after a user has successfully been authorized. [Build the flow](https://docs.yellow.ai/docs/platform_concepts/studio/build/Flows/journeys) to execute the desired action immediately after the user's authorization.
## Set up the Google login URL on Yellow.ai
1. Go to **Automation** and [create a flow](https://docs.yellow.ai/docs/platform_concepts/studio/build/Flows/journeys) based on your usecase.
2. Include the integration node at the point in the flow where you want to authorize the user or when the bot needs to request user authorization. To accomplish this, navigate to **Integrations** and select **Google Identity Management**.
2. Click the node and fill the following fields:
* **Account name:** Select the name of the Google account you will be using.
* **Action:** Choose Generate Login URL.
* **Redirect URI:** Copy the webhook url from integration card(as mentioned here) and paste it.
* **Scope:** Enter your Google console scope seprated by space. For example, openid https://www.googleapis.com/auth/userinfo.profile
[Store the reponse of this node](https://docs.yellow.ai/docs/platform_concepts/studio/build/bot-variables#41-store-data-in-variables) in a variable.
3. To display the URL to the user, pass this variable in a message node in this syntax ```{{variables.variable.arrayname.fieldname}}```.
---
## Instamojo integration
Instamojo is a popular payment gateway in India that enables businesses to accept payments online through multiple channels such as UPI, debit/credit cards, net banking, wallets, and more. With this integration, you can connect your AI Agent to Instamojo to initiate and manage payment requests, track transaction statuses, and ensure a secure payment experience for your customers.
This guide provides step-by-step instructions to help you:
1. Set up your Instamojo API credentials
2. Create and manage payment links
Handle payment callbacks and statuses
Ensure compliance and best practices for secure transactions
Whether you're building an e-commerce site, a digital service platform, or a donation portal, this integration helps streamline your payment collection process with minimal effort.
## Get required API credentials from Instamojo
To integrate Instamojo with your application, you need the following credentials:
- **API Key**
- **Auth Token**
- **Private Salt (for webhook verification, if required)**
- **Client ID & Client Secret** (for OAuth2 flows, in some cases)
Follow these steps to get them:
1. Create or Log in to Your Instamojo Account
- Go to [https://www.instamojo.com](https://www.instamojo.com) and log in to your **Merchant Dashboard** .
2. Go to **Dashboard** > Go to** API & Plugins** > **Generate Credentials** > Select **Direct Rest API Integration**.
3. Generate Your API Credentials
- On the Developers page, go to the section **“API Credentials”** and click **"Generate Credentials"** or **"Create New App"**, if prompted.
You will receive **API Key**, **Auth Token**, and **Private Salt**.
:::note
Credentials vary between **Test Mode** and **Live Mode**. Use **test credentials** while integrating for testing, and **live credentials** only when you're ready for production.
* __Test Mode:__ This mode is intended for testing purposes and for developers who are just beginning their integration with Instamojo. Test Mode is completely free of charge but requires completion of KYC (Know Your Customer) verification. No actual charges will be incurred, even if valid card details are provided on the [Instamojo test environment](https://test.instamojo.com) for sign-up.
* __Live mode__: In Live Mode, transactions occur in real-time, and actual charges apply. To operate in Live Mode, users must provide their bank account information and complete the KYC (Know Your Customer) process. This ensures compliance with regulatory requirements and enables seamless processing of payments. To get started with Live Mode, visit [Instamojo's website](https://www.instamojo.com/) and sign up for an account.
:::
## Connect Instamojo with Yellow.ai
Follow these steps to begin integrating:
You need to integrate first with Development/Staging or Sandbox environment. Once the integration is complete and the application is published, all connected integrations will be available in the Live environment.
1. On the [Cloud platform](https://cloud.yellow.ai), Navigate to the Development/Staging environment and click **Extensions** > **Integrations** > **Payment** > **Instamojo**.
2. In **Give account name**, enter a unique name for the integration. You can use only lowercase alphanumeric characters and underscores (_).
3. Enter the **Client ID** and **Client Secret** that was captured using the previous section.
4. In Instamojo base URL. for sandbox environment use ```https://test.instamojo.com``` as baseUrl and for production env use ```https://api.instamojo.com``` as baseUrl.
3. To add multiple accounts, click **+ Add account** and follow the above mentioned steps. You can add a maximum of 5 merchant accounts.
----
## Enable Instamojo related events for the AI agent
**Instamojo payment status event**: Indicates an update in the payment status. . Instamojo primarily recognizes the following payment status values: Pending, Sent, Failed, and Completed.
* To activate an event, refer to [this section](/docs/platform_concepts/appConfiguration/overview#step-3-configure-webhook-url).
* To trigger a AI agent flow using the activated event, click [here](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/overview#step-5-trigger-bot-flows-with-integration-events).
## Perform Instamojo actions from your AI Agent
This integration enables the AI agent to perform the following Instamojo actions:
* Generate payment link
* Create refund
1. Go to Development/Staging environment and navigate to **Automation** > **Build** > Select the flow where you want to add the Generate payment link node.
2. Click **Add node** > **Integrations** > **Instamojo**.
### Generate Payment link
This action allows you to generate payment link at any point in a conversation.
Here's a detailed and user-friendly table for the **"Generate Payment Link"** action using Instamojo, following the same format and tone as your previous API field description tables:
#### Field descriptions for Generate payment link
| **Field** | **Description** |
|----------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Amount*** | The exact amount to be charged from the customer. This should be a numeric value, typically in INR (e.g., 499.00). |
| **Customer email*** | The email address of the customer who will receive the payment link. This is used for communication and transaction tracking. |
| **Customer mobile number*** | The mobile number of the customer. Instamojo can use this to send the payment link via SMS. |
| **Customer name*** | Full name of the customer. Helps personalize the payment experience and is often required for recordkeeping. |
| **Purpose*** | A short description of what the payment is for (e.g., "Product Purchase", "Subscription", "Consultation Fee"). This will be shown to the customer. |
| **Send email*** | A boolean value (`true` or `false`). If set to `true`, Instamojo will send the payment link to the customer via email. |
| **Send SMS*** | A boolean value (`true` or `false`). If `true`, the payment link will also be sent via SMS to the customer's mobile number. |
| **Status callback URL*** | The endpoint (URL) where Instamojo should send status updates about the payment (e.g., success, failure). Useful for backend workflows and confirmation logic. Copy Webhook URL from the Instamojo card at the integration page. Example: `https://dummyurl.yellowmessenger.com/integrations/genericIntegration/instamojo/x16450274?id=l%2B%2FD1yhpida7KtXeCEVUofPRsNBY%3D`| |
| **Parse API response** | When enabled, the system will parse and store key fields from the Instamojo response automatically (like payment ID, link URL, etc.). |
#### Sample success response
```json
{
"id": "05f317448ad84649aa1a9c7328edb015",
"user": "https://api.instamojo.com/v2/users/90f01dfdacbe4fe7892fc27dbdc30906/",
"phone": "+919999999999",
"email": "foo@example.com",
"buyer_name": "John Doe",
"amount": "2500",
"purpose": "FIFA 16",
"status": "Pending",
"payments": [],
"send_sms": true,
"send_email": true,
"sms_status": "Pending",
"email_status": "Pending",
"shorturl": null,
"longurl": "https://www.instamojo.com/@foo/05f317448ad84649aa1a9c7328edb015",
"redirect_url": "http://www.example.com/redirect/",
"webhook": "http://www.example.com/webhook/",
"created_at": "2016-05-09T16:10:13.786Z",
"modified_at": "2016-05-09T16:10:13.786Z",
"resource_uri": "https://api.instamojo.com/v2/payment_requests/05f317448ad84649aa1a9c7328edb015/",
"allow_repeated_payments": false,
"mark_fulfilled": true
}
```
### Create refund action
Use this action to initiate Instamojo refund directly from the AI Agent.
**Parameters required to process the request**
Sure! Here's the updated table with the required fields marked with an asterisk (*) **only in the first column**, and the "Required" column removed for clarity:
---
### Field descriptiond for Create refund action
| **Field** | **Type** | **Description** |
|----------------------------------|------------|-----------------|
| **Description*** | `string` | A short explanation of the reason for the refund. This helps provide context to the Instamojo team or for internal tracking. |
| **Payment ID*** | `string` | The unique payment identifier generated when the customer made the payment. This ID is required to locate and process the correct transaction. |
| **Refund Amount*** | `number` | The amount to be refunded. If the full amount is to be refunded, enter the total transaction amount. Partial refunds are allowed only once. |
| **Unique Transaction ID*** | `string` | A unique ID you define for the refund request. Helps in tracking and reconciling the refund operation. Must be unique for each refund call. |
| **Issue Type*** | `string` | A standardized refund reason code accepted by Instamojo. Allowed values:• `RFD` – Duplicate/Delayed payment• `TNR` – Product/service not available• `QFL` – Customer not satisfied• `QNR` – Product lost/damaged• `EWN` – Digital download issue• `TAN` – Event was canceled• `PTH` – Other issues |
| **Parse API Response** | *(System-handled)* | Automatically extracts and formats the API response for use in subsequent actions. Typically enabled for smooth workflows. |
**Sample success response**
```json
{
"refund": {
"id": "C5c0751269",
"payment_id": "MOJO5c04000J30502939",
"status": "Refunded",
"type": "QFL",
"body": "Customer isn't satisfied with the quality",
"refund_amount": "100",
"total_amount": "100.00",
"created_at": "2015-12-07T11:01:37.640Z"
},
"success": true
}
```
:::info
**Reference**
For more information about the action nodes you use here, refer to [Create Payment](https://docs.instamojo.com/reference/create-a-payment-request-1), [webhooks](https://docs.instamojo.com/reference/what-is-a-webhook).
:::
---
## Integration FAQs
### Payments
How to generate a payment link in a flow?
1. Go to **Automation Build** and build a flow for your use case.
2. At the point in the conversation where you want to display the payment link, add the **Integrations** node.
- Drag the node connector and navigate to **Integrations**.
- Select the payment gateway you've integrated.
3. In the integrations node, fill in the following fields:
- **Account name:** Choose the payment gateway account.
If you have only one account, it will be auto-populated. If you have multiple, the first one added is selected by default.
- **Action:** Select **Generate Payment Link**.
4. Fill in the corresponding fields as per your integration setup.
5. Store the JSON response from the payment node in a variable and [display the API response](https://docs.yellow.ai/docs/platform_concepts/studio/api/add-api-apinode#display-api-response) in a [message node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/message-nodes1/message-nodes) so users can click the link and proceed with the payment.
### MoEngage
How to enable MoEngage?
The MoEngage integration is a gated feature and can be enabled based on your request. To enable MoEngage, you can reach out to our support team at support@yellow.ai for assistance.
---
## Intercom Live Chat
## Configuration
Inside your project, navigate to the Integrations tab and on the left side bar select Live Chat. You will find Intercom Live chat
Copy webhook details from the Integrations page and enter it in Settings -> Webhooks.
Add conversations.admin.replied and conversations.admin.closed topics.
You’ll need to provide an Intercom access token, which you can find inside your intercom developer app → Configure → Authentication → Access Token. Then click on connect.
If you have multiple accounts, follow the above mentioned steps to add each of them.
:::note
1. Enter a unique name for each account to easily identify them within the yellow.ai platform. It is recommended to use a name that aligns with its purpose for better usability.
2. You can add a maximum of 15 accounts.
3. In a two-tier environment, such as bots with only Development/Live environments, you can add account names only in the development mode. Once added and flows have been built, in the Live mode, you can only choose the account names and not edit them.
4. In a three-tier environment, such as bots with Staging/Sandbox/Production modes, in Staging and Sandbox modes, you can add and edit new accounts. However, in Production, only the account details added in Staging will be available. You can only map in the production environment.
:::
## Use Case
In this integration you can use raise ticket node to create a conversation with intercom agent and once conversation initiates the user can talk to the intercom agent, once the conversation between them ends bot takes over the conversation with user.
:::note
When multiple accounts are added, select the appropriate account for each node, allowing you to leverage the unique functionalities of each account for their intended purposes.
:::
### Events
Following are the events which are currently accommodated in the Integration:
:::info
Use **Ticket-closed** in the **Raise Ticket node** to perform specific actions when a live chat closes, instead of using the **ticket-close** event.
:::
Event | Description
----- | -----------
intercom_message_reply | This event reaches to bot when intercom agent sends a reply to the user.
intercom_agent_assigned | This event reaches to bot when any of the intercom agent accepts your ticket.
ticket-closed | This event reaches to bot when intercom agent closes the user ticket.
:::info
If you have added multiple accounts in your platform, enable events for each of those accounts.
:::
## Support
- The text and attachments (image, file, video) are being supported from both user and agent side.
- Custom fields:
1. Go to Contacts -> All Users -> Most Recent Contact.
2. Under the Qualification section you can see the Settings icon. Click on it, you'll be redirected to the Qualifications Settings page.
3. By clicking on the Add Data button, you can see the option to Add New Data which is used to add custom fields.
4. In the bot, you can see a field for “Intercom Live Agent Custom Fields” (if intercom integration is connected). Assign a variable of type object to this field.
5. That object variable needs to have custom fields as keys.
## Reference
https://developers.intercom.com/intercom-api-reference/reference#conversation-model
---
## Jira
# Scope of Integration
Yellow.ai Integration with Jira allows you to seamlessly connect your jira cloud with the yellow.ai platform. Using this integration, one can create issue, view issue details, create project, get project details or get user details.
:::note
Atlassian and JIRA are different integrations available on the yellow.ai platform. To use them, you must set them up individually.
:::
## Configuration
Configuring the integration with jira iis straightforward. Follow the steps defined below to start integrating:
1. Create an application on [https://developer.atlassian.com/console/myapps/](https://developer.atlassian.com/console/myapps/)
2. Select Oauth 2.0 integration
3. Go to Console -> My apps -> youAppName -> Permission -> jira Api then click on add
4. Add and configure your app’s API scopes.
5. Then Go to Authorization and copy the url from integration card then configure the url there. \
6. Go to setting then copy client Id and client Secret then paste in to integration form and connect. It is oauth based integration hence jira will ask to give access to above app then allow. Then you can use jira integration action node.
7. Get ApiToken value for using inside the action-node. follow the below steps
Click on Profile icon on top-right -> Manage Account -> Security -> API Token -> Create and manage API tokens -> create new API token and copy the value and paste somewhere for your reference.
8. If you have multiple accounts, follow the above mentioned steps to add each of them.
:::note
1. Enter a unique name for each account to easily identify them within the yellow.ai platform. It is recommended to use a name that aligns with its purpose for better usability.
2. You can add a maximum of 5 merchant accounts.
3. In a two-tier environment, such as bots with only Development/Live environments, you can add account names only in the development mode. Once added and flows have been built, in the Live mode, you can only choose the account names and not edit them.
4. In a three-tier environment, such as bots with Staging/Sandbox/Production modes, in Staging and Sandbox modes, you can add and edit new accounts. However, in Production, only the account details added in Staging will be available. You can only map in the production environment.
:::
## Use-cases
Following are the use-cases which are currently accommodated in the Integration:
:::note
When multiple accounts are added, select the appropriate account for each node, allowing you to leverage the unique functionalities of each account for their intended purposes.
:::
### Get Issue Details:-
From this method you can get the issue details.
_Node Input Params:-_
| | | |
|---|---|---|
| Field Name | Sample Input | Remarks|
| issueIdOrKey* | INTG-189 | Issue Key or Issue Id.|
#### Output Response should be stored in object type variables
### Get Project Details:-
From this method you can get Project Details.
_Node Input Params:-_
| | | |
|---|---|---|
| Field Name| Sample Input| Remarks|
| projectIdOrKey* | INTG or 10004 | Project Key or Project Id.|
#### OutPut Response should be stored in Object type variables
### Get Project Status:-
From this method you can get Project Status Details.
_Node Input Params:-_
| | | |
|---|---|---|
| Field Name| Sample Input| Remarks|
| projectIdOrKey* | INTG or 10004 | Project Key or Project Id.|
#### Output Response should be stored in Array type variables
### Create Jira Issue:-
Creates an issue or, where the option to create subtasks is enabled in Jira, a subtask. A transition may be applied, to move the issue or subtask to a workflow step other than the default start step, and issue properties set.
Creating a subtask differs from creating an issue as follows:
`issueType` must be set to a subtask issue type .
`parent` must contain the ID or key of the parent issue.
This action node is based on V2 action node in which field are fetching dynamically.
Following the above steps will connect your Google Sheets with Yellow.ai platform.
### Search user Details:-
From this method you can fetch user details.Finds users with a structured query and returns a [paginated](https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/#pagination) list of user details
_Node Input Params:-_
| | | |
|---|---|---|
| Field Name| Sample Input| Remarks|
| userNameOrEmail*| manish.kumar@yellow.ai| Username or emal.|
#### Output Response should be stored in Array type variable.
### Create Project:-
From this method you can create project..
_Node Input Params:-_
| | | |
|---|---|---|
| Field Name | Sample Input | Remarks |
| nameOfProject* | Example Project | Name of Project |
| key| INTG| Unique Key value |
| projectTypeKey| Bussiness,Software | Project type Key enums(Bussiness, Software,Cloud)|
| leadAccountId| 16 digit varchar | Account Id of user, use search user details action node to get accountId|
| email | manish.kumar@yellow.ai | Jira Email address of person who creating project|
| apiToken| a12Esjsjs!23| Api Token|
| jiraCompanyDomain| yellowmessenger| Subdomain name of jira board|
#### ProjectTypeKey Enums- `business, service_desk, software`
#### Response Should be stored in Object type variables.
### Search issues by query:-
Returns lists of issues matching a query string. Use this resource to provide auto-completion suggestions when the user is looking for an issue using a word or string.
_Node Input Params_
| | | |
|---|---|---|
| Field Name| Sample Input Remarks|
| query* | Test Issue | Search Query of issue.|
#### Response should be stored in object type variables
---
## JSON Web Token (JWT) Integration
This guide explains how to integrate JWT authentication with your application. JWTs allow the secure exchange of information between a client and server using a signed, compact token.
#### RFC 7519 defines JWT (JSON Web Token).
A JWT is a compact, URL-safe token that represents claims securely between two parties. It typically consists of three parts separated by dots:
* **Header** – specifies the algorithm and token type.
* **Payload** – contains the claims (such as user ID, roles, and expiry).
* **Signature** – ensures integrity and authenticity, created using a secret or private key.
Example structure:
```
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9. // Header (base64url)
eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvbiBEb2UifQ. // Payload (base64url)
TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ // Signature
```
* **Signing**: Usually done with a private key (RS256, ES256) or a shared secret (HS256).
* **Verification**: Usually done with the corresponding public key.
### RFC 7517 defines JWK (JSON Web Key).
A JWK is a JSON object that represents a cryptographic key in a standard, interoperable format.
Example JWK (RSA):
```
{
"kty": "RSA", // Key type (RSA, EC, oct for symmetric, etc.)
"use": "sig", // (Optional) Intended use (sig = signature, enc = encryption)
"alg": "RS256", // (Optional) Algorithm this key is meant for
"kid": "1", // (Optional) Key ID (to identify the key in a set)
"n": "base64url...", // RSA modulus
"e": "AQAB" // RSA exponent
}
```
### JWK Set (JWKS)
A JWKS is a JSON object containing an array of keys:
```
{
"keys": [
{ ...JWK1... },
{ ...JWK2... }
]
}
```
:::info
JWTs are a compact, URL-safe means of representing claims to be transferred between two parties. They are commonly used for authentication and authorization in APIs.
:::
### Public webhook URL
```html
https://{region}.cloud.yellow.ai/api/galaxy/miscellaneous/jwks/{botId}
```
**Example**
`https://r3.cloud.yellow.ai/api/galaxy/miscellaneous/jwks/x1753349177435`
---
## Prerequisites
- Access to your application’s backend code.
- An installed JWT library for your programming language (e.g., `jsonwebtoken` for Node.js, `PyJWT` for Python).
- A secret key (for symmetric algorithms) or a private/public key pair (for asymmetric algorithms) to sign the tokens.
---
## Steps to Integrate JWT in the Platform
Follow these steps to configure the JWT integration within the yellow.ai platform.
1. In the platform, navigate to your **Development** or **Staging** environment.
2. Go to **Extensions** > **Integrations** and select the **JSON Web Token** integration from the **Tools & Utilities** category.
3. In the **Account Name** field, enter a unique name for this integration.
- Use only lowercase letters, numbers, and underscores (`_`).
- This name cannot be changed after the account is created.
:::note
Your account name should be unique and permanent. Choose carefully before saving.
:::
4. In **Signing algorithm**, select your desired algorithm. Here’s a simple breakdown:
* **HS256 / HS384 / HS512 (Symmetric):** Uses a **single shared secret key** to both create and verify a token. It's simpler but requires both parties to have the same secret.
* **RS256 / RS384 / RS512 (Asymmetric):** Uses a **private key** to create the token and a corresponding **public key** to verify it. This is more secure for distributed systems, as the private key never needs to be shared.
* **ES256 / ES384 (Asymmetric):** A more modern and efficient asymmetric algorithm using Elliptic Curve cryptography. It offers strong security with smaller key sizes compared to RSA.
5. In **Private key**, paste your private key if you are using an asymmetric algorithm (RS or ES series).
6. In **Public key**, paste your public key if you are using an asymmetric algorithm.
7. Enable **Expose Public Key as JWK** if your workflow requires the public key to be available at a JWK Set endpoint.
8. Click **Connect**.
---
## Best Practices
:::caution Security Best Practices
- **Set a Short Expiration:** Always set a reasonable expiration time (`exp` claim) for tokens to limit the impact of a potential leak.
- **Use HTTPS:** Never transmit JWTs over non-encrypted connections.
- **Secure Storage:** Store tokens securely on the client-side. For web applications, storing them in HTTP-only cookies is safer than Local Storage to prevent XSS attacks.
:::
## Using JWT in Your Application
Once integrated, you will generate and verify tokens in your application's backend.
### 1. Generate a JWT
After a user successfully authenticates (e.g., with a username and password), your server should generate a JWT to send back to them.
:::tip
Always keep your signing secret safe. Use environment variables instead of hardcoding secrets in your source code.
:::
```javascript
const jwt = require('jsonwebtoken');
// The data you want to include in the token
const payload = {
id: 1,
username: 'john_doe'
};
const secretKey = process.env.JWT_SECRET;
const options = { expiresIn: '1h' }; // Token expires in 1 hour
const token = jwt.sign(payload, secretKey, options);
console.log('Generated Token:', token);
```
```python
secret_key = "your_secret_key"
payload = {
"id": 1,
"username": "john_doe",
"exp": datetime.datetime.utcnow() + datetime.timedelta(hours=1)
}
token = jwt.encode(payload, secret_key, algorithm="HS256")
print("Generated Token:", token)
```
### 2. Verify a JWT
On subsequent requests, the client will send the JWT (usually in an Authorization header). Your server must verify its signature to ensure the request is authentic.
```javascript
const token = '...'; // Token received from the client
const secretKey = process.env.JWT_SECRET;
try {
const decoded = jwt.verify(token, secretKey);
console.log('Decoded Payload:', decoded);
// User is authenticated, proceed with the request
} catch (err) {
console.error('Invalid token:', err.message);
// Authentication failed
}
```
```python
token = '...' # Token received from the client
secret_key = "your_secret_key"
try:
decoded_payload = jwt.decode(token, secret_key, algorithms=["HS256"])
print("Decoded Payload:", decoded_payload)
# User is authenticated, proceed
except jwt.ExpiredSignatureError:
print("Token has expired.")
except jwt.InvalidTokenError:
print("Invalid token.")
```
---
Here’s a **clear, professional guide** for configuring the **JSON Web Token Action Node**:
---
## **Configuring JSON Web Token (JWT) Action Node**
The JWT node allows you to **sign** (create) and **verify** (decode) JSON Web Tokens. Follow the instructions below based on your chosen action:
### **1. Sign JWT**
This action creates a signed JWT token from a JSON payload.
**Steps:**
1. **Account Name**:
Select the configured JWT account from the dropdown.
2. **Action**:
Choose **Sign JWT**.
3. **JWT Payload (object)**:
* Select or provide the **JSON object** that you want to sign.
* Example:
```json
{
"userId": "12345",
"role": "admin"
}
```
This payload will be encoded and signed using your account's secret key.
4. **Parse API Response (Optional)**:
* If you want to process the generated token (e.g., extract parts of it), select a function here.
5. **Output**:
The node returns a signed JWT string. Store it in a variable for later use (e.g., for authentication or API calls).
---
### **2. Verify JWT**
This action verifies an existing JWT token and decodes its payload.
**Steps:**
1. **Account Name**:
Select the configured JWT account from the dropdown.
2. **Action**:
Choose **Verify JWT**.
3. **JWT Token (string)**:
* Select the variable containing the **signed JWT string** you want to verify.
* Alternatively, click **Or** to enter the token manually.
4. **Parse API Response (Optional)**:
* You can choose a function to extract or process specific values from the decoded payload.
5. **Output**:
The node returns:
* The **decoded JSON object** if verification succeeds.
* An error if the token is invalid or expired.
---
## Kapture CRM Live Chat
Yellow.ai’s integration with [Kapture CRM](https://www.kapture.cx/) lets you connect with the live chat agents of **Kapture CRM** to resolve your queries.
## 1. Connect Kapture CRM with Yellow.ai
To connect your yellow.ai account with Kapture CRM follow these steps.
### 1.1 Enable the integration in Yellow.ai's **Integration** module
1. Login to [cloud.yellow.ai](https://cloud.yellow.ai/auth/login) and click the **Integrations** module on the top left corner of your screen.
2. Search for **Kapture CRM Live Chat** or choose the category named **Live chat** from the left navigation bar and then click on **Kapture CRM Live Chat**.
3. Fill in the required fields.
* **Company Name** (To be provided by the client/kapture spoc of the client)
* **Vendor Name** (To be provided by the client/kapture spoc of the client)
* **Company Number** (To be provided by the client/kapture spoc of the client)
4. Once you're done, click **Connect**.
5. If you have multiple accounts, follow the above mentioned steps to add each of them.
:::note
1. Enter a unique name for each account to easily identify them within the yellow.ai platform. It is recommended to use a name that aligns with its purpose for better usability.
2. You can add a maximum of 15 accounts.
3. In a two-tier environment, such as bots with only Development/Live environments, you can add account names only in the development mode. Once added and flows have been built, in the Live mode, you can only choose the account names and not edit them.
4. In a three-tier environment, such as bots with Staging/Sandbox/Production modes, in Staging and Sandbox modes, you can add and edit new accounts. However, in Production, only the account details added in Staging will be available. You can only map in the production environment.
:::
### 1.2 Configure webhook URL in Kapture CRM Dashboard
To receive events, you need to configure the webhook URL in the **Kapture CRM Dashboard**.
Copy the webhook url and the api key mentioned in the **Instructions** section of the **Kapture CRM Integration** Card. Append the region of your bot to the domain of the webhook url. r1/r2/r3/r4/r5 are the regions of your bot, you can refer the following list for the same.
* r1 = MEA
* r2 = Jakarta
* r4= USA
* r5 = Europe
* r3 = Singapore
For example, if the domain is https://cloud.yellow.ai, you need to change it to https://r1.cloud.yellow.ai if the region of the bot is r1. If the bot belongs to India, you can use origin domain itself.
## 2. Use-case
This integration lets you connect with live agents on the **Kapture CRM** platform from your yellow.ai account.
:::note
When multiple accounts are added, select the appropriate account for each node, allowing you to leverage the unique functionalities of each account for their intended purposes.
:::
### 2.1 Chat with Kapture CRM's Live Agent
:::info
Use **Ticket-closed** in the **Raise Ticket node** to perform specific actions when a live chat closes, instead of using the **ticket-close** event.
:::
1. In the Automation flow builder, select the **Raise Ticket** node.
2. Select **Kapture CRM Live Chat** from the **Live chat agent** drop-down list.
The following table contains the details of each field of the **Raise ticket** node.
| Field name | Sample value | Data type |Description
| -------- | -------- | -------- |-----|
|Message after ticket assignment|Requesting live agent connection.|String| The message that will be displayed to the end user after a ticket is successfully assigned to an agent|
|Name| Rajesh|String|Name of the end user|
|Mobile| 9870000000| String|Mobile number of the end user|
Email|test@gmail.com|String|Email address of the end user
Query|I have a concern regarding my flight ticket|String| The subject/topic/reason why the ticket was created|
Priority|MEDIUM|String|The priority of the ticket|
You can enable **Advanced Options** to access the advanced features of this node.
**Sample success response**
```
{
"assignedTo": true,
"success": true,
"status": "ASSIGNED",
"ticketInfo": "{{apiresponse}}"
}
```
:::note
apiresponse represents the raw response from the Kapture CRM create ticket API
:::
**Sample failure response**
```
{
"success": false,
"assignedTo": false,
"agentNotAvailable": true,
"message": "TicketId is not created and transferring the control back to the bot",
"ticketInfo": "{{apiresponse}}"
}
```
:::note
apiresponse represents the raw response from the Kapture CRM create ticket API
:::
---
## Konnect Insights
Integrate Yellow.ai with **Konnect Insights** to seamlessly forward user and bot interactions for sentiment analysis. This integration empowers Konnect Insights to analyze user sentiments and enables agents to respond directly from the Konnect Insights dashboard. This integration enables two key purposes:
1. **Ticket Creation**: Yellow.ai generates tickets in Konnect Insights as soon as a ticket is created in Yellow.ai, sending chat conversations for sentiment analysis, aiding agent understanding.
2. **Agent Conversations**: All agent interactions within Yellow.ai are forwarded to Konnect Insights for comprehensive analysis.
## Connect Yellow.ai with Konnect Insights
To integrate these two platforms, follow the steps mentioned below:
### Create an app in Konnect Insights
You need to create an app in Konnect Insights with the yellow.ai bot credentials to connect the specifc bot with Konnect Insights.
1. Go to your [Konnect Insights account](https://app3.konnectinsights.com/) click the **hamburger icon** on the top left > **settings** > **All apps** > Search for **Yellow Bot** > **Connect**.
2. In the following pop-up, fill in the following fields:
* **Profile name:** Enter a name for your profile in Konnect Insights.
* **Bot ID:** Enter your bot ID. For steps to fetch your bot ID, click [here](https://docs.yellow.ai/docs/platform_concepts/get_started/publish-env#finding-your-bot-id).
* **Webhook URL:** Copy this from Yellow.ai's integration page and paste it here. To do so:
* Go to cloud.yellow.ai > **Integrations** > **Custom live agent** > click **Webhook URL** at the top right corner to copy it.
3. Click **Save**. The app will be added to **Integrated Apps**.
### Fetch credentials from the app
1. In the **Integrated Apps** page, click the **gear icon** next to the profile you created in the previous step and click **Get Information**.
2. Copy the **Domain Name**, **Company Name** and **API Key** from here.
### Authorize Yellow.ai to access Konnect Insights
1. Go to cloud.yellow.ai > **Integrations** > **Custom Live Agent** and fill in the following fields.
| Field Name | Description |
|-------------------------------|------------------------------------------------------------------------------------------------------------------|
| Account name | Provide a name to the Konnect Insights account you connect here. |
| Domain name | Paste the domain name copied in the previous step. |
| API Key | Paste the API key copied in the previous step. |
| API timeout (in seconds) | Time within which Yellow.ai fails to receive an API response from Konnect Insights. |
| Ticket queue message | When a ticket enters the queue, the end user must wait until the next available agent is free, during which time a message will be sent to keep the user informed. |
| Send conversation history JSON| Send the conversation history to Konnect Insights in the JSON format. |
2. Click **Connect** after filling the fields.
## Create tickets and share user messages to Konnect Insights via bot conversations
1. Go to **Automation** and [build a flow](https://docs.yellow.ai/docs/platform_concepts/studio/build/Flows/journeys#2-create-a-flow) based on how you want the bot to take the user through the process.
2. Include the [Raise ticket node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/raise-ticket) at the point in the flow where you want to let the user talk to a live agent. To accomplish this, include a Raise ticket node and choose **Custom Live Agent** under **Live chat agent**.
3. Fill in the following fields in the node. The variables chosen for these fields must be previously collected in the flow via node. To know more about this in detail, click [here](https://docs.yellow.ai/docs/platform_concepts/studio/build/bot-variables#41-store-data-in-variables).
| Field name | Data type | Description | Sample value |
|------------|-----------|-------------|--------------|
| Live chat agent | - | - | Choose **Custom Live Agent** in the drop-down |
| Account name | String | Choose the Genesys account to which the chats should be transferred | account1 |
| Message after ticket assignment | String | The message that will be displayed to the end user after a ticket is successfully assigned to an agent | Requesting live agent connection. |
| Name | String | Name of the end user | John |
| Mobile | String | Mobile number of the end user | 9870000000 |
| Email | String | Email address of the end user. This is a mandatory field | test@gmail.com |
| Query | String | The subject/topic/reason why the ticket was created | I have a concern regarding my flight ticket |
| Priority | String | The priority of the ticket | MEDIUM |
You can enable **Advanced Options** to set the priority, auto-translation, custom fields, tags and department.
4. Once you have set up the flow, chats will automatically get forwarded to **Konnect Insights** when this flow gets triggered and user starts responding to agents.
**On Yellow.ai bot:**
**On Konnect Insights:**
---
## LeadSquared Whatsapp Connector Integration
The **LeadSquared WhatsApp Connector (Cloud API)** connects Yellow.ai with LeadSquared’s Converse platform over the **WhatsApp Cloud API** contract. LeadSquared sends business-initiated notifications (approved WhatsApp templates) to your customers through your Yellow.ai WhatsApp Business number, and Yellow.ai syncs the delivery status of each notification back to LeadSquared.
:::info How it works
Yellow.ai acts as the **WhatsApp Cloud API endpoint** for LeadSquared. Instead of pointing LeadSquared at Meta, you point its **Send Message URL** at Yellow.ai and authenticate with a **Permanent Access Token** that Yellow.ai generates for your bot. The connector covers **outbound notifications** (LeadSquared → customer) and **delivery status** (Yellow.ai → LeadSquared).
:::
## Prerequisites
Before you begin, ensure you have:
- A **WhatsApp Business number already connected on Yellow.ai** — notifications are sent through this number.
- At least one **approved WhatsApp template**.
- **Super Admin** permissions on both **Yellow.ai** and **LeadSquared**.
You do not need a separate API token, username, or password — Yellow.ai generates the required credentials for you on the integration page.
---
## Step 1: Add the connector in Yellow.ai
1. In Yellow.ai, go to **Extensions** → **Integrations**.
2. Search for **LeadSquared WhatsApp Connector (Cloud API)** and open it.
3. Yellow.ai shows the setup instructions along with the credentials generated for your bot. Keep this page open — you will copy these values into LeadSquared in the next step:
- **Send Message URL** — `https:///integrations/leadSquared/v2/v17.0//messages`
- **Permanent Access Token** — the access token generated for your bot.
- **WhatsApp Business Account ID** — your bot identifier.
- **Postback URL** — `https:///integrations/galaxyNotification/leadsquare/v2/` (used in Step 4).
---
## Step 2: Configure WhatsApp Business in LeadSquared
Refer to the official help guide: [LeadSquared WhatsApp Cloud API Integration](https://help.leadsquared.com/leadsquared-whatsapp-integration-with-whatsapp-cloud-api/).
1. In your LeadSquared account, go to **Apps** → **Apps Marketplace**.
2. Search for **WhatsApp Business**, open it, and click **Settings** → **Configure**.
3. Click **Add Number** and fill in the basic details.
4. In the **Service Provider** step, select **WhatsApp Cloud API**.
5. In the **Authentication** step, provide the values from Step 1:
| LeadSquared field | Value |
|---|---|
| **Send Message URL** | `https:///integrations/leadSquared/v2/v17.0//messages` |
| **Permanent Access Token** | The access token from the Yellow.ai integration page. |
| **WhatsApp Business Account ID** | Your bot identifier (shown on the Yellow.ai integration page). |
| **WhatsApp Business Number** | Your registered WABA number, e.g. `91XXXXXXXXXX`. |
6. **Save** the details and **refresh** the page.
---
## Step 3: Complete the setup in Yellow.ai
1. In LeadSquared, copy the **Notifications Webhook URL** that was generated after saving.
2. Back on the Yellow.ai integration page, fill in the connector form:
- **WhatsApp Business Number** → your registered WABA number (e.g. `91XXXXXXXXXX`). Notifications are sent through this number.
- **Webhook url** → paste the **Notifications Webhook URL** copied from LeadSquared.
3. Click **Connect** to save the connector.
---
## Step 4: Enable the Notification API Engine in Yellow.ai
To sync delivery status back to LeadSquared, enable the Notification API Engine and configure the postback URL.
1. Copy the **Postback URL** shown on the integration page (`https:///integrations/galaxyNotification/leadsquare/v2/`).
2. In your bot, go to **Engagement** → **Preferences**.
3. Enable the **Notification API Engine**.
4. Turn on the **Postback URL** option and paste the copied URL in the **Send the delivery status to** field.
5. Click **Save**.
---
## Verify Integration
1. Trigger a notification from LeadSquared using an approved WhatsApp template.
2. Confirm the message is delivered to the recipient on WhatsApp.
3. In LeadSquared, confirm that the delivery status (sent / delivered / read) is updated for the notification.
---
## Troubleshooting
- **401 Unauthorized when LeadSquared sends a message** → Re-copy the **Permanent Access Token** and **Send Message URL** from the Yellow.ai integration page; the token is specific to your bot. Confirm the **WhatsApp Business Account ID** matches your bot identifier.
- **Message not delivered** → Ensure the **WhatsApp Business Number** in the connector form is a number already connected on Yellow.ai and that the WhatsApp template is approved. Only approved templates (business-initiated notifications) are supported.
- **Delivery status not updating in LeadSquared** → Confirm the **Postback URL** is enabled under **Engagement → Preferences → Notification API Engine**, and that the **Webhook url** on the connector form is the Notifications Webhook URL from LeadSquared.
---
## Related Resources
- [Yellow.ai Integrations Overview](/docs/nexus/appConfiguration/overview)
- [LeadSquared WhatsApp Cloud API Integration (LeadSquared help)](https://help.leadsquared.com/leadsquared-whatsapp-integration-with-whatsapp-cloud-api/)
---
## Live Chat Integration on app.yellow.ai
This integration will allow the customers who are using bots on app.yellow.ai to use the updated live chat integration on cloud.yellow.ai.
## 1. Use cases
The following are the use-cases of this integration:
### 1.1 Amazon connect live agent
To connect with an Amazon Connect Live Agent, use this code-snippet
```
app.raiseTicketForThirdPartyLiveChat({
issue: "Test Issue",
contact: {
phone: "9870000000",
name: "Raj",
email: "Test@email.com"
},
amazonConnectLiveAgentCustomFields: {customFields: {test: “yes”}}
}).then((ticketData) => {
app.log(ticketData, "ticketData");
// Display appropriate message based on the ticketData
}).catch((error) => {
app.log(error, 'error');
//Error handler
});
```
This table consists of sample values, data types and descriptions for all the fields that need to be filled.
| Field name| Sample value |Data type |Description|
| -------- | -------- | -------- |-------|
| issue | Test description | String |The subject/topic/reason why the ticket is created.
|phone|9870000000| String |Mobile number of the end user.|
|email|test@gmail.com | String |Email address of the end user.|
name| Rajesh | String| Name of the end user.|
|amazonConnectLiveAgentCustomFields| `{customFields: {test: “yes”}}` |Object| Custom key: value pairs associated with the end user required to raise a ticket. You need to pass the value of this key as {}, in case no key: pairs are required.|
**Sample response in case of success**
```
{
"assignedTo": true,
"success": true,
"status": "ASSIGNED",
"ticketInfo": "{{apiresponse}}"
}
```
:::note
apiresponse represents the raw response from the amazon connect create ticket API
:::
**Sample response in case of failure**
```
{
"success": false,
"assignedTo": false,
"agentNotAvailable": true,
"message": "TicketId is not created and transferring the control back to the bot",
"ticketInfo": "{{apiresponse}}"
}
```
:::note
apiresponse represents the raw response from the amazon connect create ticket API
:::
### 1.2 Avaya Live Agent
To connect with an Avaya Live Agent, use this code-snippet
```json
app.raiseTicketForThirdPartyLiveChat({
issue: "Test Issue",
contact: {
phone: "9870000000",
name: "Raj",
email: "Test@email.com"
}
}).then((ticketData) => {
app.log(ticketData, "ticketData");
// Display appropriate message based on the ticketData
}).catch((error) => {
app.log(error, 'error');
//Error handler
});
```
This table consists of sample values, data types and descriptions for all the fields in the that need to be filled.
| Field name| Sample value |Data type |Description|
| -------- | -------- | -------- |-------|
| issue | Test description | String |The subject/topic/reason why the ticket is created.
|phone|9870000000| String |Mobile number of the end user.|
|email|test@gmail.com | String |Email address of the end user.|
name| Rajesh | String| Name of the end user.|
**Sample response in case of success**
```
{
"assignedTo": true,
"success": true,
"message": "Agent is available and ticket is assigned to the agent",
"status": "ASSIGNED",
"ticketInfo": "{{apiresponse}}"
}
```
:::note
apiresponse represents the raw response from the avaya create ticket API
:::
**Sample response in case of failure**
```
{
"success": false,
"assignedTo": false,
"agentNotAvailable": true,
"message": "Agent availability is false and hence not assigned to any agent.",
"ticketInfo": "{{apiresponse}}"
}
```
:::note
apiresponse represents the raw response from the avaya create ticket API
:::
### 1.3 Custom Live Agent
To connect with a Custom Live Agent, use this code-snippet
```json
app.raiseTicketForThirdPartyLiveChat({
issue: "Test Issue",
contact: {
phone: "9870000000",
name: "Raj",
email: "Test@email.com"
},
category: "Sales",
priority: "MEDIUM",
customLiveAgentCustomFields: {customFields: {test: “yes”}}
}).then((ticketData) => {
app.log(ticketData, "ticketData");
// Display appropriate message based on the ticketData
}).catch((error) => {
app.log(error, 'error');
//Error handler
});
```
This table consists of sample values, data types and descriptions for all the fields in the that need to be filled.
| Field name| Sample value |Data type |Description|
| -------- | -------- | -------- |-------|
| issue | Test description | String |The subject/topic/reason why the ticket is created.
|phone|9870000000| String |Mobile number of the end user.|
|email|test@gmail.com | String |Email address of the end user.|
name| Rajesh | String| Name of the end user.|
|category|Sales|String | Category under which the ticket will be created.|
|priority|MEDIUM|String | Priority of the ticket to be created.|
|customLiveAgentCustomFields| `{customFields: {test: “yes”}}` | Object| Custom key:value pairs associated with the end user required to raise a ticket. You need to pass the value of this key as {}, in case no key:pairs are required.
**Sample response in case of success**
```json
{
"assignedTo": true,
"success": true,
"status": "ASSIGNED",
"ticketInfo": "{{apiresponse}}"
}
```
:::note
apiresponse represents the raw response from the custom live agent create ticket API
:::
**Sample response in case of failure**
```
{
"success": false,
"assignedTo": false,
"agentNotAvailable": true,
"message": "Agent is unavailable to chat with the end user, hence transferring the control back to the bot.",
"ticketInfo": "{{apiresponse}}"
}
```
:::note apiresponse represents the raw response from the custom live agent create ticket API
:::
### 1.4 Freshchat Live Agent
To connect to a Freshchat Live Agent, please use this code-snippet:
```
app.raiseTicketForThirdPartyLiveChat({
issue: "Test Issue",
contact: {
phone: "9870000000",
name: "Raj",
email: "Test@email.com"
},
assignedGroupId: "test-group",
freshChatUserId: "3554-cbcbc-dchchc",
freshChatUniqueIdentifier: "testInfo",
properties: [],
freshChatChannelId: "abce-ddede-eded-3454"
}).then((ticketData) => {
app.log(ticketData, "ticketData");
// Display appropriate message based on the ticketData
}).catch((error) => {
app.log(error, 'error');
//Error handler
});
```
This table consists of sample values, data types and descriptions for all the fields in the that need to be filled.
| Field name | Sample value | Data type | Description |
| --------------------------| ----------------------| ---------| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| issue | Test description | String | The subject/topic/reason why the ticket is created. |
| phone | 9870000000 | String | Mobile number of the user. |
| email | test@gmail.com | String | Email address of the user. |
| name | Rajesh | String | Name of the user. |
| assignedGroupId | Sales | String | Category under which the ticket will be created. |
| priority | 3554-cbcbc-dchchc | String | Freshchat groupId to which the ticket should be assigned. The default value “” should be passed for this. |
| freshChatUserId | test-group | String | Freshchat userId of the user, this is passed if the same ticket needs to be re-opened for the same user. The default value “” should be passed for this. |
| freshChatUniqueIdentifier | testInfo | Object | A unique identifier that will reflect as referenceId in the freshchat agent portal if passed. The default value “” should be passed for this. |
| properties | `[{key:”Hash”, value: “Yes”} ]` | Array | Custom properties that can be passed on while creating a ticket. |
| freshChatChannelId | abce-ddede-eded-3454 | String | This[ API](https://app.swaggerhub.com/apis-docs/Freshchat/freshchat-api/2.0.0#/Channel%20API/getAllChannels) needs to be called from Postman, which in turn will fetch the list of channel IDs associated with that Freshchat account and confirms the client's authorization to access that account. |
**Sample response in case of success**
```
{
"assignedTo": true,
"success": true,
"status": "ASSIGNED",
"ticketInfo": "{{apiresponse}}"
}
```
:::note
apiresponse represents the raw response from the freshchat live agent create ticket API
:::
Sample response in case of failure:-
```
{
"success": false,
"assignedTo": false,
"agentNotAvailable": true,
"message": "Agent is unavailable to chat with the end user, hence transferring the control back to the bot.",
"ticketInfo": "{{apiresponse}}"
}
```
::: note
apiresponse represents the raw response from the freshchat live agent create ticket API
:::
### 1.5 Kapture CRM Live Agent
To connect to a Kapture CRM Live Agent, please use this code-snippet
```json
app.raiseTicketForThirdPartyLiveChat({
issue: "Test Issue",
contact: {
phone: "9870000000",
name: "Raj",
email: "Test@email.com"
}
}).then((ticketData) => {
app.log(ticketData, "ticketData");
// Display appropriate message based on the ticketData
}).catch((error) => {
app.log(error, 'error');
//Error handler
});
```
This table consists of sample values, data types and descriptions for all the fields that need to be filled.
| Field name | Sample value | Data type |Description|
| -------- | -------- | -------- |-------|
| issue | Test description | String |The subject/topic/reason why the ticket is created.
|phone| 9870000000|String|Mobile number of the end user.|
email|test@gmail.com|String|Email address of the end user.
name|Rajesh|String|Name of the end user.|
**Sample response in case of success**
```json
{
"assignedTo": true,
"success": true,
"message": "Agent is available and ticket is assigned to the agent",
"status": "ASSIGNED",
"ticketInfo": "{{apiresponse}}"
}
```
:::note
apiresponse represents the raw response from the kapture crm create ticket API
:::
**Sample response in case of failure**
```json
{
"success": false,
"assignedTo": false,
"agentNotAvailable": true,
"message": "Agent availability is false and hence not assigned to any agent.",
"ticketInfo": "{{apiresponse}}"
}
```
:::note
apiresponse represents the raw response from the kapture crm create ticket API
:::
### 1.6 Locobuzz Live Agent
To connect to a Locobuzz Live Agent, please use this code-snippet
```json
app.raiseTicketForThirdPartyLiveChat({
issue: "Test Issue",
contact: {
phone: "9870000000",
name: "Raj",
email: "Test@email.com"
},
category: "Sales",
priority: "MEDIUM",
}).then((ticketData) => {
app.log(ticketData, "ticketData");
// Display appropriate message based on the ticketData
}).catch((error) => {
app.log(error, 'error');
//Error handler
});
```
This table consists of sample values, data types and descriptions for all the fields that need to be filled.
| Field name | Sample value | Data type |Description|
| -------- | -------- | -------- |-------|
| issue | Test description | String |The subject/topic/reason why the ticket is created.
|phone| 9870000000|String|Mobile number of the end user.|
email|test@gmail.com|String|Email address of the end user.
name|Rajesh|String|Name of the end user.|
category| Sales|String|Category under which the ticket will be created.|
priority| MEDIUM |String| Priority of the ticket to be created.|
sentiment|Happy|String|User sentiment. Default value to be passed for this key is “”.
**Sample response in case of success**
```json
{
"assignedTo": true,
"success": true,
"status": "ASSIGNED",
"ticketInfo": "{{apiresponse}}"
}
```
:::note
apiresponse represents the raw response from the locobuzz live agent create ticket API
:::
**Sample response in case of failure**
```json
{
"success": false,
"assignedTo": false,
"agentNotAvailable": true,
"message": "Agent is unavailable to chat with the end user, hence transferring the control back to the bot.",
"ticketInfo": "{{apiresponse}}"
}
```
:::note
apiresponse represents the raw response from the locobuzz live agent create ticket API
:::
### 1.7 Genesys Live Agent
To connect to a Genesys Live Agent, please use this code-snippet
```json
app.raiseTicketForThirdPartyLiveChat({
issue: "Test Issue",
contact: {
phone: "9870000000",
name: "Raj",
email: "Test@email.com"
},
genesysCustomFields: {customFields: {test: “yes”}}
}).then((ticketData) => {
app.log(ticketData, "ticketData");
// Display appropriate message based on the ticketData
}).catch((error) => {
app.log(error, 'error');
//Error handler
});
```s
This table consists of sample values, data types and descriptions for all the fields that need to be filled.
| Field name | Sample value | Data type |Description|
| -------- | -------- | -------- |---------|
| issue | Test description | String |The subject/topic/reason why the ticket is created.
phone| 9870000000 | String |Mobile number of the end user.
email| test@gmail.com |String| Email address of the end user.
name| Rajesh| String|Name of the end user.|
genesysCustomFields|{customFields: {test: “yes”}}|Object|Custom key:value pairs associated to the end user required to raise a ticket. You need to pass the value of this key as {}, in case no key:pairs are required.
**Sample response in case of success**
```json
{
"assignedTo": true,
"success": true,
"status": "ASSIGNED",
"ticketInfo": "{{apiresponse}}"
}
```
:::note
apiresponse represents the raw response from the genesys create ticket API
:::
**Sample response in case of failure**
```json
{
"success": false,
"assignedTo": false,
"agentNotAvailable": true,
"message": "TicketId is not created and transferring the control back to the bot",
"ticketInfo": "{{apiresponse}}"
}
```
:::note
apiresponse represents the raw response from genesys create ticket API
:::
### 1.8 Genesys Cloud Live Agent
To connect to a Genesys Cloud Live Agent, please use this code-snippet
```json
app.raiseTicketForThirdPartyLiveChat({
issue: "Test Issue",
contact: {
phone: "9870000000",
name: "Raj",
email: "Test@email.com"
},
genesysCloudCustomFields: {customFields: {test: “yes”}}
}).then((ticketData) => {
app.log(ticketData, "ticketData");
// Display appropriate message based on the ticketData
}).catch((error) => {
app.log(error, 'error');
//Error handler
});
```
This table consists of sample values, data types and descriptions for all the fields that need to be filled.
| Field name | Sample value | Data type |Description|
| -------- | -------- | -------- |---------|
| issue | Test description | String | The subject/topic/reason why the ticket is created.
phone|9870000000|String|Mobile number of the end user.|
email| `test@gmail.com` | String | Email address of the end user.|
name | Rajesh|String |Name of the end user.|
genesysCloudCustomFields|` {customFields: {test: “yes”}}` |Object | Custom key:value pairs associated to the end user required to raise a ticket. You need to pass the value of this key as {}, in case no key:pairs are required.|
**Sample response in case of success**
```json
{
"assignedTo": true,
"success": true,
"status": "ASSIGNED",
"ticketInfo": "{{apiresponse}}"
}
```
:::note
apiresponse represents the raw response from the genesys cloud create ticket API
:::
**Sample response in case of failure**
```json
{
"success": false,
"assignedTo": false,
"agentNotAvailable": true,
"message": "TicketId is not created and transferring the control back to the bot",
"ticketInfo": "{{apiresponse}}"
}
```
:::note
apiresponse represents the raw response from genesys cloud create ticket API
:::
### 1.9 Intercom Live Agent
To connect to an Intercom Live Agent, please use this code-snippet
```json
app.raiseTicketForThirdPartyLiveChat({
issue: "Test Issue",
contact: {
phone: "9870000000",
name: "Raj",
email: "Test@email.com"
},
intercomLiveAgentCustomFields: {customFields: {test: “yes”}}
}).then((ticketData) => {
app.log(ticketData, "ticketData");
// Display appropriate message based on the ticketData
}).catch((error) => {
app.log(error, 'error');
//Error handler
});
```
This table consists of sample values, data types and descriptions for all the fields that need to be filled.
| Field name | Sample value | Data type |Description|
| -------- | -------- | -------- |---------|
| issue | Test description | String |The subject/topic/reason why the ticket is created.
phone|9870000000|String|Mobile number of the end user.|
email|test@gmail.com |String|Email address of the end user.|
name | Rajesh|String |Name of the end user.|
intercomLiveAgentCustomFields| `{customFields: {test: “yes”}}` |Object | Custom key:value pairs associated to the end user required to raise a ticket. You need to pass the value of this key as {}, in case no key:pairs are required.|
**Sample response in case of success**
```json
{
"assignedTo": true,
"success": true,
"status": "ASSIGNED",
"ticketInfo": "{{apiresponse}}"
}
```
:::note
apiresponse represents the raw response from the intercom create ticket API
:::
**Sample response in case of failure**
```json
{
"success": false,
"assignedTo": false,
"agentNotAvailable": true,
"message": "TicketId is not created and transferring the control back to the bot",
"ticketInfo": "{{apiresponse}}"
}
```
:::note
apiresponse represents the raw response from the intercom create ticket API
:::
### 1.10 Nice Incontact Live Agent
To connect to a Nice Incontact Live Agent, please use this code-snippet
```json
app.raiseTicketForThirdPartyLiveChat({
issue: "Test Issue",
contact: {
phone: "9870000000",
name: "Raj",
email: "Test@email.com"
}
}).then((ticketData) => {
app.log(ticketData, "ticketData");
// Display appropriate message based on the ticketData
}).catch((error) => {
app.log(error, 'error');
//Error handler
});
```
This table consists of sample values, data types and descriptions for all the fields that need to be filled.
| Field name | Sample value | Data type |Description|
| -------- | -------- | -------- |---------|
| issue | Test description | String |The subject/topic/reason why the ticket is created.
phone|9870000000|String|Mobile number of the end user.|
email|test@gmail.com |String|Email address of the end user.|
name | Rajesh|String |Name of the end user.|
**Sample response in case of success**
```json
{
"assignedTo": true,
"success": true,
"status": "ASSIGNED",
"ticketInfo": "{{apiresponse}}"
}
```
:::note
apiresponse represents the raw response from the nice-incontact create ticket API
:::
**Sample response in case of failure**
```json
{
"success": false,
"assignedTo": false,
"agentNotAvailable": true,
"message": "TicketId is not created and transferring the control back to the bot",
"ticketInfo": "{{apiresponse}}"
}
```
:::note apiresponse represents the raw response from the nice-incontact create ticket API
:::
### 1.11 Talishma Live Agent
To connect to a Talishma Live Agent, please use this code-snippet
```json
app.raiseTicketForThirdPartyLiveChat({
issue: "Test Issue",
contact: {
phone: "9870000000",
name: "Raj",
email: "Test@email.com"
}
}).then((ticketData) => {
app.log(ticketData, "ticketData");
// Display appropriate message based on the ticketData
}).catch((error) => {
app.log(error, 'error');
//Error handler
});
```
This table consists of sample values, data types and descriptions for all the fields that need to be filled.
| Field name | Sample value | Data type |Description|
| -------- | -------- | -------- |---------|
| issue | Test description | String | The subject/topic/reason why the ticket is created.
phone|9870000000|String|Mobile number of the end user.|
email|test@gmail.com |String|Email address of the end user.|
name | Rajesh|String |Name of the end user.|
**Sample response in case of success**
```json
{
"assignedTo": true,
"success": true,
"status": "ASSIGNED",
"ticketInfo": "{{apiresponse}}"
}
```
:::note
apiresponse represents the raw response from the talishma create ticket API
:::
**Sample response in case of failure**
```json
{
"success": false,
"assignedTo": false,
"agentNotAvailable": true,
"message": "TicketId is not created and transferring the control back to the bot",
"ticketInfo": "{{apiresponse}}"
}
```
:::note
apiresponse represents the raw response from the talishma create ticket API
:::
### 1.12 Salesforce Live Agent
```json
app.raiseTicketForThirdPartyLiveChat({
issue: "Test Issue",
contact: {
phone: "9870000000",
name: "Raj",
email: "Test@email.com"
},
salesforceLiveChatCustomFields: [],
salesforceLiveChatCustomEntities: [],
salesforceLiveChatAgentId: "",
salesforceLiveChatAgentAssignedMessage: "",
salesforceLiveChatVisitorLanguage: "English",
salesforceLiveChatQueuePositionMessage: "",
salesforceLiveChatUpdatedQueuePositionMessage: "",
salesforceLiveChatAgentTransferredMessage: "",
salesforceLiveChatEstimatedWaitTimeMessage: "",
salesforceLiveChatDisplayAgentName: true,
salesforceLiveChatIdleTimeWarningMessage: “”,
salesforceLiveChatIdleTimeTimeoutMessage: “”,
salesforceLiveChatConnectionFailureMessage: “”,
salesforceLiveChatAgentDisconnectMessage: “”,
salesforceLiveChatAgentTimeoutMessage: “”
}).then((ticketData) => {
app.log(ticketData, "ticketData");
// Display appropriate message based on the ticketData
}).catch((error) => {
app.log(error, 'error');
//Error handler
});
```
| Field name | Sample value | Data type | Description |
| ----------------------------------------------- | -------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `issue` | Test description | String | The subject, topic, and reason for creating the ticket. |
| `phone` | 9870000000 | String | Mobile number of the user. |
| `email` | [test@gmail.com](mailto:test@gmail.com) | String | Email address of the user. |
| `name` | Rajesh | String | Name of the user. |
| `salesforceLiveChatCustomFields` | See below | Array | The details provided by the user before initiating the chat. |
| `salesforceLiveChatCustomEntities` | See below | Array | The records are created or searched based on the enabled [EntityFieldsMaps](https://developer.salesforce.com/docs/atlas.en-us.live_agent_rest.meta/live_agent_rest/live_agent_rest_data_types.htm#EntityFieldMaps). |
| `salesforceLiveChatAgentId` | 0055g00000HEbLD | String | The agentId required to enable the sticky agent feature. |
| `salesforceLiveChatAgentAssignedMessage` | You are now connected to `liveAgent`. | String | Message shown to the user after an agent is assigned. Use `` `liveAgent` `` to display the agent's name. |
| `salesforceLiveChatVisitorLanguage` | English | String | Language preferred by the user. |
| `salesforceLiveChatQueuePositionMessage` | Your queue position is `position` | String | Message shown when the ticket is in queue. Use `` `position` `` to display the queue number. |
| `salesforceLiveChatUpdatedQueuePositionMessage` | Your current queue position is `position` | String | Message shown when queue position changes. |
| `salesforceLiveChatAgentTransferredMessage` | Your chat has been transferred to `liveAgent` | String | Message shown when the chat is transferred to another agent. |
| `salesforceLiveChatEstimatedWaitTimeMessage` | The estimated wait time for the chat to get assigned is `waitTime` seconds | String | Estimated wait message. Use `` `waitTime` `` to show seconds. |
| `salesforceLiveChatDisplayAgentName` | true | Boolean | Enable to show the agent's name upon assignment. |
| `salesforceLiveChatIdleTimeWarningMessage` | Idle warning message | String | Message shown when there's user inactivity. |
| `salesforceLiveChatIdleTimeTimeoutMessage` | Idle timeout message | String | Message when the chat is terminated due to inactivity. |
| `salesforceLiveChatConnectionFailureMessage` | Connection failure | String | Message shown when there's a failure in connecting with the agent. |
| `salesforceLiveChatAgentDisconnectMessage` | Agent has disconnected | String | Message shown when an agent disconnects and others are available. |
| `salesforceLiveChatAgentTimeoutMessage` | Agent timeout occurred | String | Message when the agent timeout threshold is crossed. |
**Sample response in case of success:**
```
{
"assignedTo": true,
"success": true,
"status": "ASSIGNED",
"ticketInfo": "{{apiresponse}}"
}
```
:::note
apiresponse represents the raw response from the salesforce create ticket API
:::
**Sample response in case of failure:**
```
{
"success": false,
"assignedTo": false,
"agentNotAvailable": true,
"message": "TicketId is not created and transferring the control back to the bot",
"ticketInfo": "{{apiresponse}}"
}
```
:::note
apiresponse represents the raw response from the salesforce create ticket API
:::
## 2. Configuration
You can configure any of the above mentioned live agent integration(s) by following these steps:-
To enable the integration in the yellow.ai Integrations Module,
1. Login to app.yellow.ai, search for your bot in the **Search Projects** section and then click the bot.
2. Click the **Growth icon** on the left navigation bar.
3. Click **Data Explorer**. You will be redirected to the cloud.yellow.ai’s UI.
4. On the top left corner, click the drop-down and choose **Integrations**.
5. Configure the required live chat integration
6. .After entering the required values, click **Connect** and the integration will get enabled on yellow.ai.
---
## Llm
---
## Locobuzz Live Chat
Yellow.ai’s integration with [Locobuzz Live Chat](https://locobuzz.com/) lets you connect with the live chat agents of Lococbuzz to resolve your support queries.
## 1. Connect Locobuzz with Yellow.ai
To configure Locobuzz integration in your yellow.ai account, follow these steps.
### 1.1 Enable the integration in Yellow.ai's **Integration** module
1. Login to [cloud.yellow.ai](https://cloud.yellow.ai/auth/login) and click the **Integrations** module on the top left corner of your screen.
2. Search for **Locobuzz Live Chat** or choose the category named **Live chat** from the left navigation bar and then click on **Locobuzz Live Chat**.
3. Fill in the required fields.
* **Api Key** (To be provided by the client/locobuzz spoc of the client)
* **Company Name** (To be provided by the client/locobuzz spoc of the client)
* **Api Domain** (To be provided by the client/locobuzz spoc of the client)
* **Channel Id** (To be provided by the client/locobuzz spoc of the client)
* **Ticket Queue Message** (This message will be displayed if the ticket goes into a queued state).
4. Once you're done, click **Connect**.
5. If you have multiple accounts, follow the above mentioned steps to add each of them.
:::note
1. Enter a unique name for each account to easily identify them within the yellow.ai platform. It is recommended to use a name that aligns with its purpose for better usability.
2. You can add a maximum of 15 accounts.
3. In a two-tier environment, such as bots with only Development/Live environments, you can add account names only in the development mode. Once added and flows have been built, in the Live mode, you can only choose the account names and not edit them.
4. In a three-tier environment, such as bots with Staging/Sandbox/Production modes, in Staging and Sandbox modes, you can add and edit new accounts. However, in Production, only the account details added in Staging will be available. You can only map in the production environment.
:::
### 1.2 Configure webhook URL in Locobuzz Dashboard
To receive events, you need to configure the webhook URL in the **Locobuzz Dashboard**.
Copy the webhook url and the api key mentioned in the **Instructions** section of the **Locobuzz Integration** Card. Append the region of your bot to the domain of the webhook url. r1/r2/r3/r4/r5 are the regions of your bot, you can refer the following list for the same.
* r1 = MEA
* r2 = Jakarta
* r4= USA
* r5 = Europe
* r3 = Singapore
### 1.3 Enable events in Yellow.ai bot
1. Login to cloud.yellow.ai and click the **Automation** module on the top left corner of your screen.
3. Click **Event** on the left navigation bar and click **Integrations**.
5. Enable the following events on this page:
* **locobuzz-agent-inactivity** - This event is triggered when the agent is inactive.
* **locobuzz-agent-logout** - This event is triggered when there is an unexpected network/system issue at the agent’s end.
* **locobuzz-customer-inactivity** - This event is triggered when the customer is inactive for more than a minute. Activate this event by clicking the three dots next to the name of the event.
4. After activating these events, a flow needs to be created in [Automation](https://docs.yellow.ai/docs/platform_concepts/studio/overview) whose trigger point will be this event. Based on the received event data, an appropriate message will be displayed to the end user.
:::info
If you have added multiple accounts in your platform, enable events for each of those accounts.
:::
**Sample webhook event data sent by Locobuzz:**
```
{
"ticketId": 287267,
"senderId": "8f800f85-6143-4710-8b3a-1f4c3e4fa2b0",
"source": "yellowmessenger",
"event": "customer-infoawaited",
"agentName": "Prashant Pange",
"agentId": "33619",
"ticketAssignedTime": 1665476293
}
```
## 2. Use-case
This integration lets you connect with live agents on **Locobuzz** from your yellow.ai account.
:::note
When multiple accounts are added, select the appropriate account for each node, allowing you to leverage the unique functionalities of each account for their intended purposes.
:::
### 2.1 Chat with Locobuzz Live Agent
:::info
Use **Ticket-closed** in the **Raise Ticket node** to perform specific actions when a live chat closes, instead of using the **ticket-close** event.
:::
1. In the Automation flow builder, select the **Raise Ticket** node.
2. Select **Locobuzz Live Chat** from the **Live chat agent** drop-down list.
The following table contains the details of each field of the **Raise ticket** node.
| Field name | Sample value | Data type |Description
| -------- | -------- | -------- |-----|
|Message after ticket assignment|Requesting live agent connection.|String| The message that will be displayed to the end user after a ticket is successfully assigned to an agent|
|Name| Rajesh|String|Name of the end user|
|Mobile| 9870000000| String|Mobile number of the end user|
Email|test@gmail.com|String|Email address of the end user
Query|I have a concern regarding my flight ticket|String| The subject/topic/reason why the ticket was created|
Priority|Medium|String|The priority of the ticket|
**Sample success response**
```
{
"assignedTo": true,
"success": true,
"status": "ASSIGNED",
"ticketInfo": "{{apiresponse}}"
}
```
:::note
apiresponse represents the raw response from the Locobuzz create ticket API
:::
**Sample failure response**
```
{
"success": false,
"assignedTo": false,
"agentNotAvailable": true,
"message": "TicketId is not created and transferring the control back to the bot",
"ticketInfo": "{{apiresponse}}"
}
```
:::note
apiresponse represents the raw response from the Locobuzz create ticket API
:::
---
## Magento Integration
Yellow.ai’s integration with Magento helps you connect your yellow.ai platform with your Magento store. This will allow your customers to view the categories of your inventory, and view products by categories. You can also get your customer details via email. Additionally, your customers can place an order and check their order status via order ID.
## 1. Connect Magento with Yellow
Follow the below-mentioned steps to connect your Magento account with Yellow.ai
### 1.1 Generate OAuth credentials on Magento
1. Login into Magento admin panel. If your Magento store URL is https://magentostore.in , the admin panel URL will be https://magentostore.in/admin
2. Click **SYSTEM** in the left menu and click **Integrations**.
3. Click the **Add New Integration** button on the following page.
4. Fill in the **Name** and **password** (Magento admin password) fields in **Integration Info**. The rest of the fields can be empty.
5. Click the **API** section on the left menu, and edit **Resource Access** to **All**.
6. Expand all the buttons on the top-right corner and click **Save & Activate**.
7. Click **Allow** button to generate the API credentials.
8. Copy these credentials to any text editor. We will need them to connect the Yellow.ai platform to Magento.
9. Go to https://cloud.yellow.ai and click **Integrations**.
11. Search for **Magento** in the **All Integrations** field.
12. Fill in the fields and click **Connect**.
13. If you have multiple accounts, follow the above mentioned steps to add each of them.
:::note
1. Enter a unique name for each account to easily identify them within the yellow.ai platform. It is recommended to use a name that aligns with its purpose for better usability.
2. You can add a maximum of 15 accounts.
3. In a two-tier environment, such as bots with only Development/Live environments, you can add account names only in the development mode. Once added and flows have been built, in the Live mode, you can only choose the account names and not edit them.
4. In a three-tier environment, such as bots with Staging/Sandbox/Production modes, in Staging and Sandbox modes, you can add and edit new accounts. However, in Production, only the account details added in Staging will be available. You can only map in the production environment.
:::
14. Once Magento is connected to yellow.ai, you can see **Magento** in the **Integrations** node.
## 2. Use-cases
The following are the use-cases accommodated in this integration:
:::note
When multiple accounts are added, select the appropriate account for each node, allowing you to leverage the unique functionalities of each account for their intended purposes.
:::
### 2.1 Get all the categories
This action doesn’t require any input from the user. It displays all the categories and their subcategories from the **Magento** default store to the user.
**Sample Response:**
```
{
"id": 1,
"parent_id": 0,
"name": "Root Catalog",
"is_active": null,
"position": 0,
"level": 0,
"product_count": 0,
"children_data": [
{
"id": 2,
"parent_id": 1,
"name": "Default Category",
"is_active": true,
"position": 1,
"level": 1,
"product_count": 0,
"children_data": [
{
"id": 3,
"parent_id": 2,
"name": "Electronics",
"is_active": true,
"position": 1,
"level": 2,
"product_count": 2,
"children_data": []
}
]
}
]
}
```
### 2.2 Get customer details by email
This action gets customer details through email addresses.
**Node Input Params:**
| Field Name | Sample Input Name | Remarks |
| -------- | -------- | -------- |
| email | jhon.doe@yellow.ai | String Type |
**Sample Response:**
```
{"items": [
{
"id": 1,
"group_id": 1,
"default_billing": "1",
"default_shipping": "1",
"created_at": "2022-09-23 11:38:30",
"updated_at": "2022-09-29 09:09:26",
"created_in": "Default Store View",
"email": "john.doe@yellow.ai",
"firstname": "john",
"lastname": "doe",
"store_id": 1,
"website_id": 1,
"addresses": [
{
"id": 1,
"customer_id": 1,
"region": {
"region_code": "AL",
"region": "",
"region_id": 43
},
"region_id": 343,
"country_id": "IN",
"street": [
""
],
"telephone": "999999999",
"postcode": "333333",
"city": "",
"firstname": "john",
"lastname": "doe",
"default_shipping": true,
"default_billing": true
}
],
"disable_auto_group_change": 0,
"extension_attributes": {
"is_subscribed": false
}
}]}
```
### 2.3 Retrieve order details by order Id
Retrieves order details by order ID.
**Node Input Params:**
| Field Name | Sample Input | Remarks |
| -------- | -------- | -------- |
| orderId | 632910392 | String Type |
**Sample Response:**
```
{
"base_currency_code": "USD",
"base_discount_amount": 0,
"base_grand_total": 37,
"base_discount_tax_compensation_amount": 0,
"base_shipping_amount": 5,
"base_shipping_discount_amount": 0,
"base_shipping_discount_tax_compensation_amnt": 0,
"base_shipping_incl_tax": 5,
"base_shipping_tax_amount": 0,
"base_subtotal": 32,
"base_subtotal_incl_tax": 32,
"base_tax_amount": 0,
"base_total_due": 37,
"base_to_global_rate": 1,
"base_to_order_rate": 1,
"billing_address_id": 2,
"created_at": "2022-09-29 09:09:26",
"customer_email": "john.johndoe@yellow.ai",
"customer_firstname": "john",
"customer_group_id": 1,
"customer_id": 1,
"customer_is_guest": 0,
"customer_lastname": "johndoe",
"customer_note_notify": 1,
"discount_amount": 0,
"entity_id": 1,
"global_currency_code": "USD",
"grand_total": 37,
"discount_tax_compensation_amount": 0,
"increment_id": "000000001",
"is_virtual": 0,
"order_currency_code": "USD",
"protect_code": "43203977547c781b449c6ef4f5445d68",
"quote_id": 1,
"remote_ip": "172.18.0.1",
"shipping_amount": 5,
"shipping_description": "Flat Rate - Fixed",
"shipping_discount_amount": 0,
"shipping_discount_tax_compensation_amount": 0,
"shipping_incl_tax": 5,
"shipping_tax_amount": 0,
"state": "new",
"status": "pending",
"store_currency_code": "USD",
"store_id": 1,
"store_name": "Main Website\\nMain Website Store\\nDefault Store View",
"store_to_base_rate": 0,
"store_to_order_rate": 0,
"subtotal": 32,
"subtotal_incl_tax": 32,
"tax_amount": 0,
"total_due": 37,
"total_item_count": 1,
"total_qty_ordered": 1,
"updated_at": "2022-09-29 09:09:27",
"weight": 5,
"items": [
{
"amount_refunded": 0,
"base_amount_refunded": 0,
"base_discount_amount": 0,
"base_discount_invoiced": 0,
"base_discount_tax_compensation_amount": 0,
"base_original_price": 32,
"base_price": 32,
"base_price_incl_tax": 32,
"base_row_invoiced": 0,
"base_row_total": 32,
"base_row_total_incl_tax": 32,
"base_tax_amount": 0,
"base_tax_invoiced": 0,
"created_at": "2022-09-29 09:09:26",
"discount_amount": 0,
"discount_invoiced": 0,
"discount_percent": 0,
"free_shipping": 0,
"discount_tax_compensation_amount": 0,
"is_qty_decimal": 0,
"is_virtual": 0,
"item_id": 1,
"name": "Acer Laptop",
"no_discount": 0,
"order_id": 1,
"original_price": 32,
"price": 32,
"price_incl_tax": 32,
"product_id": 1,
"product_type": "simple",
"qty_canceled": 0,
"qty_invoiced": 0,
"qty_ordered": 1,
"qty_refunded": 0,
"qty_shipped": 0,
"quote_item_id": 1,
"row_invoiced": 0,
"row_total": 32,
"row_total_incl_tax": 32,
"row_weight": 5,
"sku": "Acer Laptop",
"store_id": 1,
}
],
"billing_address": {...},
"payment_additional_info": [
{
"key": "method_title",
"value": "Check / Money order"
}
],
"applied_taxes": [],
"item_applied_taxes": []}
}
```
### 2.4 Get Product Details by Product Id
Fetches the details of the specified product id.
**Node Input Params:**
| Field Name | Sample Input | Remarks |
| -------- | -------- | -------- |
| productId | 5 | String Type |
**Sample Response:**
```json
{
"items": [
{
"id": 1,
"sku": "Acer Laptop",
"name": "Acer Laptop",
"attribute_set_id": 4,
"price": 32,
"status": 1,
"visibility": 4,
"type_id": "simple",
"created_at": "2022-09-28 11:35:33",
"updated_at": "2022-09-28 11:35:33",
"weight": 5,
"extension_attributes": {
"website_ids": [
1
],
"category_links": [
{
"position": 0,
"category_id": "3"
}
]
},
"product_links": [],
"options": [],
"media_gallery_entries": [],
"tier_prices": [],
"custom_attributes": [
{
"attribute_code": "page_layout",
"value": "product-full-width"
},
{
"attribute_code": "options_container",
"value": "container2"
},
{
"attribute_code": "url_key",
"value": "acer-laptop"
},
{
"attribute_code": "msrp_display_actual_price_type",
"value": "0"
},
{
"attribute_code": "gift_message_available",
"value": "2"
},
{
"attribute_code": "required_options",
"value": "0"
},
{
"attribute_code": "has_options",
"value": "0"
},
{
"attribute_code": "meta_title",
"value": "Acer Laptop"
},
{
"attribute_code": "meta_keyword",
"value": "Acer Laptop"
},
{
"attribute_code": "meta_description",
"value": "Acer Laptop "
},
{
"attribute_code": "tax_class_id",
"value": "2"
},
{
"attribute_code": "category_ids",
"value": [
"3"
]
}
]
}
],
"search_criteria": {
"filter_groups": [
{
"filters": [
{
"field": "entity_id",
"value": "1",
"condition_type": "eq"
}
]
}
]
},
"total_count": 1
}
```
### 2.5 Get all the products
Retrieves the list of all the available products.
**Sample Response:**
```json
{
"items": [
{
"id": 1,
"sku": "Acer Laptop",
"name": "Acer Laptop",
"attribute_set_id": 4,
"price": 32,
"status": 1,
"visibility": 4,
"type_id": "simple",
"created_at": "2022-09-28 11:35:33",
"updated_at": "2022-09-28 11:35:33",
"weight": 5,
"extension_attributes": {
"website_ids": [
1
],
"category_links": [
{
"position": 0,
"category_id": "3"
}
]
},
"product_links": [],
"options": [],
"media_gallery_entries": [],
"tier_prices": [],
"custom_attributes": [
{
"attribute_code": "page_layout",
"value": "product-full-width"
},
{
"attribute_code": "options_container",
"value": "container2"
},
{
"attribute_code": "url_key",
"value": "acer-laptop"
},
{
"attribute_code": "msrp_display_actual_price_type",
"value": "0"
},
{
"attribute_code": "gift_message_available",
"value": "2"
},
{
"attribute_code": "required_options",
"value": "0"
},
{
"attribute_code": "has_options",
"value": "0"
},
{
"attribute_code": "meta_title",
"value": "Acer Laptop"
},
{
"attribute_code": "meta_keyword",
"value": "Acer Laptop"
},
{
"attribute_code": "meta_description",
"value": "Acer Laptop "
},
{
"attribute_code": "tax_class_id",
"value": "2"
},
{
"attribute_code": "category_ids",
"value": [
"3"
]
}
]
},
{
"id": 2,
"sku": "Samsung TV",
"name": "Samsung TV",
"attribute_set_id": 4,
"price": 323,
"status": 1,
"visibility": 4,
"type_id": "simple",
"created_at": "2022-09-28 11:36:21",
"updated_at": "2022-09-28 11:36:21",
"weight": 424,
"extension_attributes": {
"website_ids": [
1
],
"category_links": [
{
"position": 0,
"category_id": "3"
}
]
},
"product_links": [],
"options": [],
"media_gallery_entries": [],
"tier_prices": [],
"custom_attributes": [
{
"attribute_code": "page_layout",
"value": "product-full-width"
},
{
"attribute_code": "options_container",
"value": "container2"
},
{
"attribute_code": "url_key",
"value": "samsung-tv"
},
{
"attribute_code": "msrp_display_actual_price_type",
"value": "0"
},
{
"attribute_code": "gift_message_available",
"value": "2"
},
{
"attribute_code": "required_options",
"value": "0"
},
{
"attribute_code": "has_options",
"value": "0"
},
{
"attribute_code": "meta_title",
"value": "Samsung TV"
},
{
"attribute_code": "meta_keyword",
"value": "Samsung TV"
},
{
"attribute_code": "meta_description",
"value": "Samsung TV "
},
{
"attribute_code": "tax_class_id",
"value": "2"
},
{
"attribute_code": "category_ids",
"value": [
"3"
]
},
{
"attribute_code": "country_of_manufacture",
"value": "IN"
}
]
}
],
"search_criteria": {
"filter_groups": []
},
"total_count": 2
}
```
### 2.6 Get all the products by category
Retrieves the products based on a specific category ID.
**Node Input Params:**
| Field Name | Sample Input | Remarks |
| -------- | -------- | -------- |
| categoryId | 2 | String |
**Sample Response:**
```json
{
"items": [
{
"id": 1,
"sku": "Acer Laptop",
"name": "Acer Laptop",
"attribute_set_id": 4,
"price": 32,
"status": 1,
"visibility": 4,
"type_id": "simple",
"created_at": "2022-09-28 11:35:33",
"updated_at": "2022-09-28 11:35:33",
"weight": 5,
"extension_attributes": {
"website_ids": [
1
],
"category_links": [
{
"position": 0,
"category_id": "3"
}
]
},
"product_links": [],
"options": [],
"media_gallery_entries": [],
"tier_prices": [],
"custom_attributes": [
{
"attribute_code": "page_layout",
"value": "product-full-width"
},
{
"attribute_code": "options_container",
"value": "container2"
},
{
"attribute_code": "url_key",
"value": "acer-laptop"
},
{
"attribute_code": "msrp_display_actual_price_type",
"value": "0"
},
{
"attribute_code": "gift_message_available",
"value": "2"
},
{
"attribute_code": "required_options",
"value": "0"
},
{
"attribute_code": "has_options",
"value": "0"
},
{
"attribute_code": "meta_title",
"value": "Acer Laptop"
},
{
"attribute_code": "meta_keyword",
"value": "Acer Laptop"
},
{
"attribute_code": "meta_description",
"value": "Acer Laptop "
},
{
"attribute_code": "tax_class_id",
"value": "2"
},
{
"attribute_code": "category_ids",
"value": [
"3"
]
}
]
},
{
"id": 2,
"sku": "Samsung TV",
"name": "Samsung TV",
"attribute_set_id": 4,
"price": 323,
"status": 1,
"visibility": 4,
"type_id": "simple",
"created_at": "2022-09-28 11:36:21",
"updated_at": "2022-09-28 11:36:21",
"weight": 424,
"extension_attributes": {
"website_ids": [
1
],
"category_links": [
{
"position": 0,
"category_id": "3"
}
]
},
"product_links": [],
"options": [],
"media_gallery_entries": [],
"tier_prices": [],
"custom_attributes": [
{
"attribute_code": "page_layout",
"value": "product-full-width"
},
{
"attribute_code": "options_container",
"value": "container2"
},
{
"attribute_code": "url_key",
"value": "samsung-tv"
},
{
"attribute_code": "msrp_display_actual_price_type",
"value": "0"
},
{
"attribute_code": "gift_message_available",
"value": "2"
},
{
"attribute_code": "required_options",
"value": "0"
},
{
"attribute_code": "has_options",
"value": "0"
},
{
"attribute_code": "meta_title",
"value": "Samsung TV"
},
{
"attribute_code": "meta_keyword",
"value": "Samsung TV"
},
{
"attribute_code": "meta_description",
"value": "Samsung TV "
},
{
"attribute_code": "tax_class_id",
"value": "2"
},
{
"attribute_code": "category_ids",
"value": [
"3"
]
},
{
"attribute_code": "country_of_manufacture",
"value": "IN"
}
]
}
],
"search_criteria": {
"filter_groups": []
},
"total_count": 2
}
```
### 2.7 Customer Login
This action generates a token for the particular customer which is required for adding items to the cart and placing an order.
**Node Input Params:**
| Field Name | Sample Input | Remarks |
| -------- | -------- | -------- |
| User Name | johndoe@gmail.com | String Type |
|password | yellow@123 | String Type|
**Show Response:**
```
eyJraWQiOiIxIiwiYWxnIjoiSFMyNTYifQ.eyJ1aWQiOjEsInV0eXBpZCI6MywiaWF0IjoxNjY2MTczNDg5LCJleHAiOjE2NjYxNzcwODl9.e3T7G0MWKsWHaJMUkgAG6gMTAptjuE3isG0MLn6bFzg
```
### 2.8 Create Cart
This action generates a unique cartId(quote_id) for the particular customer.
**Node Input Params:**
| Field Name | Sample Input | Remarks |
| -------- | -------- | -------- |
| customertoken | eyJraWQiOiIxIiwiYWxnIjoiSFMyNTYifQ.ey | String Type Generated using customer login action |
**Sample Response:**
```
{
"body": "5"
}
```
### 2.9 Add product to cart
This action helps to add the products to customer's cart.
**Node Input Params:**
| Field Name | Sample Input | Remarks |
| -------- | -------- | -------- |
| customertoken | eyJraWQiOiIxIiwiYWxnIjoiSFMyNTYifQ.ey | String Type Generated using customer login action |
|Product Details |`{Qty:3,Sku:”acer-laptop”....}`| Object Type |
**Sample Response:**
```json
{
"item_id": 4,
"sku": "Acer Laptop",
"qty": 1,
"name": "Acer Laptop",
"price": 32,
"product_type": "simple",
"quote_id": "2"
}
```
### 2.10 Get Cart Items
Fetches the list of products that currently exist in the cart.
| Field Name | Sample Input | Remarks |
| -------- | -------- | -------- |
| customertoken | eyJraWQiOiIxIiwiYWxnIjoiSFMyNTYifQ.ey|String TypeGenerated using customer login action|
**Sample Response:**
```json
{
"body": [
{
"item_id": 4,
"sku": "Acer Laptop",
"qty": 1,
"name": "Acer Laptop",
"price": 32,
"product_type": "simple",
"quote_id": "2"
}
]
}
```
### 2.11 Get Countries
Retrieves a list of countries and their regions. This data helps in filling up the billing and shipping details while placing an order.
**Sample response:**
```json
{
"id": "IN",
"two_letter_abbreviation": "IN",
"three_letter_abbreviation": "IND",
"full_name_locale": "India",
"full_name_english": "India",
"available_regions": [
{
"id": "569",
"code": "AN",
"name": "Andaman and Nicobar Islands"
},
{
"id": "570",
"code": "AP",
"name": "Andhra Pradesh"
},
{
"id": "571",
"code": "AR",
"name": "Arunachal Pradesh"
},
{
"id": "572",
"code": "AS",
"name": "Assam"
},
{
"id": "573",
"code": "BR",
"name": "Bihar"
},
{
"id": "574",
"code": "CH",
"name": "Chandigarh"
},
{
"id": "575",
"code": "CT",
"name": "Chhattisgarh"
}
]
}
```
### 2.12 Estimate Shipping Cost
This action estimates the shipping cost for the products that exist in the cart and provides the available shipping methods.
**Node Input Params:**
| Field Name | Sample Input | Remarks |
| -------- | -------- | -------- |
| customertoken | eyJraWQiOiIxIiwiYWxnIjoiSFMyNTYifQ.ey|String TypeGenerated using customer login action|
|Address| `{ region:”IN”, region_code:”AP”, street:[“stree1”,”stree2”], firstname:”John”, lastname:”Doe”……}`| Object Type |
**Sample Response:**
```
{
"body": [
{
"carrier_code": "flatrate",
"method_code": "flatrate",
"carrier_title": "Flat Rate",
"method_title": "Fixed",
"amount": 10,
"base_amount": 10,
"available": true,
"error_message": "",
"price_excl_tax": 10,
"price_incl_tax": 10
}
]
}
```
### 2.13 Set Shipping and Billing Info
Updates the shipping and billing information provided by the customer and displays the available payment methods to place an order.
**Node Input Params:**
| Field Name | Sample Input | Remarks |
| -------- | -------- | -------- |
| customertoken | eyJraWQiOiIxIiwiYWxnIjoiSFMyNTYifQ.ey|String TypeGenerated using customer login action|
|Address| `{ region:”IN”, region_code:”AP”, street:[“stree1”,”stree2”], firstname:”John”, lastname:”Doe”……}`| Object Type |
**Sample Response:**
```
{"payment_methods":[{"code":"checkmo","title":"Check / Money order"}],"totals":{"grand_total":74,"base_grand_total":74,"subtotal":64,"base_subtotal":64,"discount_amount":0,"base_discount_amount":0,"subtotal_with_discount":64,"base_subtotal_with_discount":64,"shipping_amount":10,"base_shipping_amount":10,"shipping_discount_amount":0,"base_shipping_discount_amount":0,"tax_amount":0,"base_tax_amount":0,"weee_tax_applied_amount":null,"shipping_tax_amount":0,"base_shipping_tax_amount":0,"subtotal_incl_tax":64,"shipping_incl_tax":10,"base_shipping_incl_tax":10,"base_currency_code":"USD","quote_currency_code":"USD","items_qty":2,"items":[{"item_id":9,"price":32,"base_price":32,"qty":2,"row_total":64,"base_row_total":64,"row_total_with_discount":0,"tax_amount":0,"base_tax_amount":0,"tax_percent":0,"discount_amount":0,"base_discount_amount":0,"discount_percent":0,"price_incl_tax":32,"base_price_incl_tax":32,"row_total_incl_tax":64,"base_row_total_incl_tax":64,"options":"[]","weee_tax_applied_amount":null,"weee_tax_applied":null,"name":"Acer Laptop"}],"total_segments":[{"code":"subtotal","title":"Subtotal","value":64},{"code":"shipping","title":"Shipping & Handling (Flat Rate - Fixed)","value":10},{"code":"tax","title":"Tax","value":0,"extension_attributes":{"tax_grandtotal_details":[]}},{"code":"grand_total","title":"Grand Total","value":74,"area":"footer"
}]}}
```
### 2.14 Edit Cart Item
This action helps in updating the quantity of a particular item in the cart.
**Node Input Params**:
| Field Name | Sample Input | Remarks |
| -------- | -------- | -------- |
| customertoken | eyJraWQiOiIxIiwiYWxnIjoiSFMyNTYifQ.ey|String TypeGenerated using customer login action|
|Address| `{ region:”IN”, region_code:”AP”, street:[“stree1”,”stree2”], firstname:”John”, lastname:”Doe”……}`| Object Type |
|Cart Item| `{sku:”acer-laptop”, qty:”5”, cartId:”4”}`|Object Type |
|Item id|2|String Type Retrieve from get cart items action|
**Sample Response:**
```
{
"item_id": 4,
"sku": "Acer Laptop",
"qty": 3,
"name": "Acer Laptop",
"price": 32,
"product_type": "simple",
"quote_id": "2"
}
```
### 2.15 Delete Cart Item
Removes items from the cart.
**Node Input Params:**
| Field Name | Sample Input | Remarks |
| -------- | -------- | -------- |
| customertoken | eyJraWQiOiIxIiwiYWxnIjoiSFMyNTYifQ.ey|String TypeGenerated using customer login action|
|Item id|2|String Type Retrieve from get cart items action|
**Sample Response:**
```
"true"
```
### 2.16 Create Order
This action places an order for the products in the cart and generates an order ID.
**Node Input Params:**
| Field Name | Sample Input | Remarks |
| -------- | -------- | -------- |
| customertoken | eyJraWQiOiIxIiwiYWxnIjoiSFMyNTYifQ.ey|String TypeGenerated using customer login action|
|Payment Method|check|String Type Retrieve from “set shipping and billing info” action|
|Billing Address| `{region:””, region_code:””}` |Object Type|
**Sample Response:**
```
5
```
---
## MCP Server Integration
# MCP Server Integration for Agentic AI
The MCP Data Connector allows your AI Agent to connect with multiple third-party applications configured in your MCP server.
Instead of setting up individual API connections for each integration, you can simply link supported accounts—such as HubSpot, Postgres, — and access all their available actions directly in AI agent conversations. The agent can then dynamically invoke the selected tools during a conversation or while executing workflows.
Unlike other integrations that work only with rule-based (non-AI) agents, the MCP Data Connector is purpose-built for AI Agents, allowing them to directly call and execute actions from connected applications during a conversation.
---
## Connect Third-Party Apps via MCP Data Connector
Follow these steps to connect your MCP server to the Yellow.ai platform:
1. In **Development/Staging** env, navigate to **Extensions** > **Integrations** > **MCP Connectors**.
2. Hover on the integration type you want to connect (Example: *HubSpot*) and click **+Add**.
3. In **Account Name**, enter a unique name for the account (only lowercase alphanumeric and _ are supported)
4. Provide the required connection details.
> The configuration fields vary based on the integration.
5. Click **Connect**.
6. You’ll see a list of tools (actions) available for the selected integration. Review the available tools to understand what each action does.
7. Select the required actions that you want to use in your AI agent and click **Add Tools**.
> Test any action to verify its functionality.
8. Click **Add tools**.
> You will see a confirmation message stating that your server has been saved.
9. Repeat the process to connect multiple accounts under the same MCP integration.
---
## Configuring AI Agent Actions
Once your integration apps are connected through the Data Connector, you can define how and when your AI Agent should use these integrations within conversations. This is done using the Call MCP Tool action available in the AI Agent configuration.
> Learn more about [Configuring agent and actions](/docs/platform_concepts/AIAgent/agent.md)
When you add the **Call MCP Tool** action in your conversation prompt logic with a specific action, the AI Agent can dynamically access and execute the action (tool) from the connected third-party applications.
**To configure**:
1. Go to your AI Agent and open the conversation prompt where you want to use specific integration-related actions.
2. Click **Add Action** → **Call MCP tool**.
3. Select the desired Integration Type (for example, HubSpot or Postgres).
4. Choose the Account connected through the Data Connector.
5. From the available actions list, select the specific action you want the agent to perform.
---
---
## Microsoft Dynamics 365
You can integrate Microsoft Dynamics 365 with Yellow.ai to enhance customer engagement and streamlining interactions through intelligent conversational capabilities. With this integration, you can create, update, retrieve and delete leads. Additionally, it enables you to create, update, and delete records, as well as establish links between related field records.
## Supported Microsoft D 365 CRM actions in Yellow.ai
| Actions | Descriptions |
|--------------------|----------------------------------------------------------------------------------------------------------------------------|
| Create a Lead | Generates a new lead entry within Microsoft. |
| Get Lead Details | Retrieves comprehensive lead information from the Microsoft database. |
| Update a Lead | Modifies and updates the details of a lead within the Microsoft system. |
| Delete A Lead | Removes specific lead details from the Microsoft database. |
| Create Record | Initiates the creation of a fresh record within any entity in Microsoft. |
| Associate Records | Establishes vital connections between entities in Dynamics 365, particularly useful for linking fields with complex relationships not directly supported by the create record action. |
| Picklist Options | Retrieves predefined picklist choices for all picklist-type fields within the selected entity. |
| State Options | Fetches predefined state options for all state-type fields within the selected entity. |
| Status Options | Gathers predefined status choices for all status-type fields within the selected entity. |
| Search Records | Conducts a thorough search across all records within a specific entity. |
| Update Record | Edits and updates the value within a single record. |
| Deleting Records | Erases records from the selected entities within the Microsoft system. |
## Connect Yellow.ai with Microsoft D 365 CRM
You need **Organization URL**, **Client ID**, **Client Secret** and **Tenent ID** to connect Yellow.ai with Microsoft. The following steps will take you through the process of obtaining them.
### Fetch Organization URL
The following steps will guide you through fetching Organization URL.
1. Create an account in [Microsoft Dynamic 365 Sales](https://dynamics.microsoft.com/en-gb/dynamics-365-free-trial/) and login.
2. Copy the part highlighted in the image below. This is your **Organization URL**.
### Fetch Client ID, Secret & Tenent ID
Obtain **Client ID**, **Client Secret** and **Tenant ID** from your **Microsoft Azure** App.
#### If you already have an app:
1. Log in to your [Azure portal](https://login.microsoftonline.com/organizations/oauth2/v2.0/authorize?redirect_uri=https%3A%2F%2Fportal.azure.com%2Fsignin%2Findex%2F&response_type=code%20id_token&scope=https%3A%2F%2Fmanagement.core.windows.net%2F%2Fuser_impersonation%20openid%20email%20profile&state=OpenIdConnect.AuthenticationProperties%3DtQVfqDvMB-GLv-r5OnQuupVWs6J8JIK4Rdk0xX6uS6-UAiSNPyAUmTdynCrfoVpnYb1NuoMUIUfGtQR4ysvsqR-M0ZPgkhwjg-LwgoQsSeFNWNWvmpRhcoopZCVoLC9kyFe8jGQuEi9CbDTUnL_pWVwR-IX9YDdh9pKHHV6dKY1f011zFHrTFm42MCwLhfhOILm2Ib-mjs4QfbmEauPHQOCiYms_YQUkT7A4eYYw9gj75ruN6KqF4pQUcf6UULALd8IWVaIAcF2a94_bGC7lOpvVNOGFhfDOinu1Pzu3esHDuIwvVMnDgXALOYz1Lw_vrpjIMcDEKnJ-iPk50MvicN9UEK_q4wdrfE71Buk_KR8ZDJoXlmHR7efd3meLfTF6CCYjbzeUabBCXrG5pbONhAsieUoXKIM8sox5NO7ZeMm7svBOtDvJSD59Op8aAD542ZKaobQaLkxK2n9Ro9WTWLvXdFusQcEg-nzLZo9dr_k8agnjXHNubbDVk0NQEHzd&response_mode=form_post&nonce=638362587856343176.MTk0ZWRlMGEtMDYzMi00NGVlLTg5YTgtMDg1M2Q1M2UwNTUyNjY4NzBmZTQtNmZkMS00MWY0LWJiYzItYWQ5YzgxYmE5ZDNl&client_id=c44b4083-3bb0-49c1-b47d-974e53cbdf3c&site_id=501430&client-request-id=d646f11a-4729-473d-9997-13972798cda2&x-client-SKU=ID_NET472&x-client-ver=6.30.1.0).
2. Go to **App Registeration**.
3. Click on the app you'd like to connect your bot with. Ensure it is in **Current** status.
4. Copy the Client ID and Tenant ID as highlighted in the below image.
5. Go to **Certificates & Secrets** and copy the **Value**. If it is concealed, click **+ New client secret** to generate a new secret value. Copy and store it as that would be your **Client Secret**.
6. Go to **App registrations** > **Overview** > **Redirect URIs**.
7. Click **Add URI** and and copy/ paste the webhook from Yellow.ai.
:::info
To find the webhook URL, go to **Integrations** > **CRM** > **Microsoft Dynamic 365** > Copy the URL.
:::
5. Click **Save**.
#### If you do not have an app
You need to create a new app and follow the steps mentioned above. To create a new app:
1. Log in to your [Azure portal](https://login.microsoftonline.com/organizations/oauth2/v2.0/authorize?redirect_uri=https%3A%2F%2Fportal.azure.com%2Fsignin%2Findex%2F&response_type=code%20id_token&scope=https%3A%2F%2Fmanagement.core.windows.net%2F%2Fuser_impersonation%20openid%20email%20profile&state=OpenIdConnect.AuthenticationProperties%3DtQVfqDvMB-GLv-r5OnQuupVWs6J8JIK4Rdk0xX6uS6-UAiSNPyAUmTdynCrfoVpnYb1NuoMUIUfGtQR4ysvsqR-M0ZPgkhwjg-LwgoQsSeFNWNWvmpRhcoopZCVoLC9kyFe8jGQuEi9CbDTUnL_pWVwR-IX9YDdh9pKHHV6dKY1f011zFHrTFm42MCwLhfhOILm2Ib-mjs4QfbmEauPHQOCiYms_YQUkT7A4eYYw9gj75ruN6KqF4pQUcf6UULALd8IWVaIAcF2a94_bGC7lOpvVNOGFhfDOinu1Pzu3esHDuIwvVMnDgXALOYz1Lw_vrpjIMcDEKnJ-iPk50MvicN9UEK_q4wdrfE71Buk_KR8ZDJoXlmHR7efd3meLfTF6CCYjbzeUabBCXrG5pbONhAsieUoXKIM8sox5NO7ZeMm7svBOtDvJSD59Op8aAD542ZKaobQaLkxK2n9Ro9WTWLvXdFusQcEg-nzLZo9dr_k8agnjXHNubbDVk0NQEHzd&response_mode=form_post&nonce=638362587856343176.MTk0ZWRlMGEtMDYzMi00NGVlLTg5YTgtMDg1M2Q1M2UwNTUyNjY4NzBmZTQtNmZkMS00MWY0LWJiYzItYWQ5YzgxYmE5ZDNl&client_id=c44b4083-3bb0-49c1-b47d-974e53cbdf3c&site_id=501430&client-request-id=d646f11a-4729-473d-9997-13972798cda2&x-client-SKU=ID_NET472&x-client-ver=6.30.1.0).
2. Go to **App Registeration**.
3. Click **+ New Registeration**.
4. Fill the following fields:
* **Name**: Enter a name for your App.
* **Supported account types**: Choose who all can use this app/access this API.
* **Redirect URI**: Choose **Web** from the drop down and copy/ paste the webhook from Yellow.ai.
:::info
To find the webhook URL, go to **Integrations** > **CRM** > **Microsoft Dynamic 365** > Copy the URL.
:::
5. Click **Register**.
### Authorize Yellow.ai to access Microsoft
1. On the left navigation bar, go to **Extensions** > **Integrations**.
2. Navigate to **CRM** > **Microsoft Dynamic 365**. Alternatively, you can use the Search box to find the integration app.
3. Fill in the fields with data obtained in the previous sections.
:::info
1. In a two-tier environment, add account names in Development and use them in Live.
2. In a three-tier environment, add accounts in Staging and Sandbox, and they'll be available in Production.
:::
4. Click **Connect**.
5. You can add up to 15 accounts. To add another Zoho CRM account, click on **Add account** and follow the steps mentioned above.
## Manage Microsoft D 365 CRM via Yellow.ai bot
To manage your Microsoft D 365 CRM account through yellow.ai bot, follow these steps:
1. Go to **Automation** and [create a flow](https://docs.yellow.ai/docs/platform_concepts/studio/build/Flows/journeys#2-create-a-flow) based on your requirement.
2. In whichever point you want the bot to access **Microsoft D 365 Sales**, inlcude the Microsoft D 365 Sales node. For that drag the node connector, go to **Integrations** > **Microsoft dynamics 365**.
3. In the **Microsoft dynamics 365** node, fill the following:
* **Account name:** Choose the Microsoft account. If you have only one account, the account name is automatically populated. If you have multiple accounts, the first account added is auto-populated. Select the one you want to use at that moment.
* **Action:** Choose the [action](#supported-microsoft-d-365-crm-actions-in-yellowai) to be performed.
* **Select Objects:** Choose the Microsoft entity in which the chosen action should be performed.
* Based on the chosen entity, collect user input for the relevant fields, [store the data in variables](https://docs.yellow.ai/docs/platform_concepts/studio/build/bot-variables#41-store-data-in-variables), and pass these variables as an input to perform the desired action.
:::info
Some action may not require selection of entities, for example, **Create a Lead**.
:::
4. Each action returns a JSON response. [Store the response in an object variable](https://docs.yellow.ai/docs/platform_concepts/studio/build/bot-variables#41-store-data-in-variables) and extract specific information from the payload. To display the response information to the user, [pass that variable](https://docs.yellow.ai/docs/platform_concepts/studio/build/bot-variables#42-retrieve-data-from-variables) to a [message node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/message-nodes1/message-nodes).
For example, if you receive the following response, you can use this syntax ``` {{{variables.variablename.companyname}}} ``` to display only the company name.
```
{
"@odata.context": "https://orgfd96595f.crm8.dynamics.com/api/data/v9.0/$metadata#leads(subject,companyname,firstname,lastname,emailaddress1,telephone1)/$entity",
"@odata.etag": "W/\"2074593\"",
"subject": "Test lead from postman",
"companyname": "Contoso",
"firstname": "bhaskar",
"lastname": "k",
"emailaddress1": "test6@gmail.com",
"telephone1": "345345345",
"leadid": "48669bf7-890c-ec11-b6e6-002248d4bce4"
}
```
---
## Microsoft Graph
### Scope of Integration
Yellow.ai Integration with Microsoft Graph allows you to seamlessly connect and use Microsoft
Graph services with yellow.ai platform. Any customer who has an Azure Active Directory will be
able to seamlessly connect and call Microsoft Graph APIs on yellow.ai platform. This connector
will enable users to get access tokens using action node which can then be used to call the
Graph APIs.
### Configuration
Configuring the integration with Microsoft Graph is straight forward. Follow the steps defined
below to start integrating:
#### 1. Navigate to Integrations Tab
Inside your project, navigate to the Configuration tab and then click on the Integrations
Tab. Search for Microsoft Graph.
#### 2. Connect to Microsoft Graph
Click on Connect and enter the values in the fields from your Azure account. Once the
values are given, the Microsoft Graph will be connected and the action node can be
used to get the access token which can then be used to call Microsoft Graph APIs.
Voila! And just like that, you are now connected and can call Microsoft Graph APIs.
If you have multiple accounts, follow the above mentioned steps to add each of them.
:::note
1. Enter a unique name for each account to easily identify them within the yellow.ai platform. It is recommended to use a name that aligns with its purpose for better usability.
2. You can add a maximum of 15 accounts.
3. In a two-tier environment, such as bots with only Development/Live environments, you can add account names only in the development mode. Once added and flows have been built, in the Live mode, you can only choose the account names and not edit them.
4. In a three-tier environment, such as bots with Staging/Sandbox/Production modes, in Staging and Sandbox modes, you can add and edit new accounts. However, in Production, only the account details added in Staging will be available. You can only map in the production environment.
:::
### Use-cases
Following are the use-cases which are currently accommodated in the Integration:
:::note
When multiple accounts are added, select the appropriate account for each node, allowing you to leverage the unique functionalities of each account for their intended purposes.
:::
#### Get access tokens
Access tokens required to call the Graph APIs can be fetched using action nodes
provided in the integration. It should be noted that necessary permissions need to be
given while registering the application on the Azure portal. For more details, please refer
https://docs.microsoft.com/en-us/graph/auth-v2-service.
### Supported Version
This integration shall support latest version releases.
For more information, please refer to Microsoft Graph Documentation.
---
## Microsoft Dynamics 365 Live Chat
Integrate your Yellow.ai account with Microsoft Dynamics 365 Live Chat and allow users to connect with live chat agents on Microsoft through the Yellow.ai bot. If your support agents are in the Microsoft account, you can establish a connection, allowing bot users to interact with those agents.
## Create an Azure bot and obtain secret keys
As a first step you need to create an Azure bot and fetch the secret keys to establish an integration.
1. Go to your [Azure Portal](https://portal.azure.com/#home) > **+ Create a resource**.
2. Search for **Azure bot** in the search box and in **Azure Bot** click **Create** > **Azure Bot**.
3. Create an Azure bot as mentioned [here](https://learn.microsoft.com/en-us/composer/quickstart-create-bot-with-azure).
4. Once you have created the bot, it looks like the screen below. Click on **Go to resource**.
5. Go to **Channels** > **Direct Line** and copy the secret keys highlighted in the image below. These keys will be entered in the Yellow.ai bot for the integration.
### Obtain client secret
You need to fetch the client secret as it is required to configure the customer service admin centre.
1. Go to [Azure Portal](https://portal.azure.com/#home) > **Manage Microsoft Entra ID** > **View**.
2. Go to **App registerations** and click the app that has the same name as the Azure Bot.
3. Generate the client secret and copy the **Application ID** or **client secret** of the Azure AD app.
### Configure Admin Centre
To configure the Admin centre, follow the steps mentioned below:
1. Open your organization URL, (sample: `https://org1a1b1c.crm8.dynamics.com/`) and click **Customer Service Admin Center**.
2. Go to **Channels** > **Messaging accounts**.
3. Create a new messaging account. Provide a name in **Name** and choose **Custom** in **Channel**. Authorize this and click **Next**.
4. In **Account details**, enter the **Microsoft app ID** and the **Client secret** (from the previous steps) and click **Validate**.
5. After validating the account details with the app ID and client secret, the platform will prompt you for custom channel configuration. Enter the details as shown in the image. Choose any name for the channel, ensure to include **custom** to help with the identification in the following configurations. Click **Add**.
6. After configuring the channel, a message endpoint URL will be generated. Click **Copy** to copy the message endpoint as this will be needed to configure the Azure Bot.
### Configure work stream
You need to configure work stream to route the chats to the right queues and right agents.
1. Open your Microsoft workspace (for example: `https://org1a53c877.crm8.dynamics.com`) > **Workstream** > **+ New workstream**. In **Name**, enter a name for your workstream and in **Type** select **Message**.
2. In **Channel**, choose **Custom** and set the **Work distribution mode** as shown in the image below. Click **Create**.
Once the workstream is created, it looks like the image below.
3. Go back to **Queues** and [create a new queue](https://learn.microsoft.com/en-us/dynamics365/customer-service/administer/queues-omnichannel?tabs=customerserviceadmincenter).
4. Go back to the workstream you created and assign this queue in the **Routing rules** for the workstream to use the queue.
5. Click **Set up Custom**.
6. Choose the created custom channel.
7. Verify the auto-populated details and click **Create Channel**.
8. Go to your Azure bot resource > **Configuration**. In **Message endpoint** paste the message endpoint obtained from the previous steps and click **Apply**.
## Authorize Yellow.ai to access Microsoft Dynamics 365 live chat
1. Go to **Integrations** > **Live chat** > **Microsoft dynamics 365 live chat**.
2. Fill in the following fields:
* **Give account name:** Provide a name to the Microsoft account you're connecting with Yellow.ai.
* **API secret:** Paste the API secret(copied from previous steps).
* **Agent timeout (in milliseconds):** Duration which the bot waits for a user input or interaction, and if no input is received within that time frame, the platform triggers a default response or take predefined actions.
3. Click **Connect**.
4. If you have multiple accounts, follow the above mentioned steps to add each of them. You can add a maximum of 15 accounts.
:::info
1. In a two-tier environment, add account names in Development and use them in Live.
2. In a three-tier environment, add accounts in Staging and Sandbox, and they'll be available in Production.
:::
## Connect bot users to live agents on Microsoft 365 Dynamic live chat
:::info
Use **Ticket-closed** in the **Raise Ticket node** to perform specific actions when a live chat closes, instead of using the **ticket-close** event.
:::
To connect your users to live chat agents on Microsoft, follow these steps:
1. Go to **Automation** and [build a flow](https://docs.yellow.ai/docs/platform_concepts/studio/build/Flows/journeys#2-create-a-flow) based on how you want the bot to take the user through the process.
2. Include the [Raise ticket node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/raise-ticket) at the point in the flow where you want the user talk to Microsoft live agent. To accomplish this, include a Raise ticket node and choose **Microsoft Dynamics 365 Live Chat** under **Live chat agent**.
3. Fill in the following fields in the node. The variables chosen for these fields must be previously collected in the flow via node. To know more about this in detail, click [here](https://docs.yellow.ai/docs/platform_concepts/studio/build/bot-variables#41-store-data-in-variables).
| Field name | Data type | Description | Sample value |
|------------|-----------|-------------|--------------|
| Live chat agent | - | - | Choose **Microsoft Dynamics 365 Live Chat** in the drop-down |
| Account name | String | Choose the Microsoft account to which the chats should be transferred | account1 |
| Message after ticket assignment | String | The message that will be displayed to the end user after a ticket is successfully assigned to an agent | Requesting live agent connection. |
| Name | String | Name of the end user | John |
| Mobile | String | Mobile number of the end user | 9870000000 |
| Email | String | Email address of the end user. This is a mandatory field | test@gmail.com |
| Query | String | The subject/topic/reason why the ticket was created | I have a concern regarding my flight ticket |
| Priority | String | The priority of the ticket | MEDIUM |
You can enable **Advanced Options** to set the priority, auto-translation, custom fields, tags and department.
4. Once you have set up the flow, chats will get automatically forwarded to live agents on Microsoft live chat when this flow gets triggered.
5. Once a user sends a message in Yellow.ai bot, the agent will receive this notification in Microsoft live. He/She needs to click **Accept** to chat with the users.
**Result:**
**On Yellow.ai bot**
**On Microsoft Live**
---
## Netcore Smartech
Yellow.ai Integration with Netcore Smartech enables the end user to do the following:
1. Receive the event from Netcore on the addition of Yellow’s webhook URL.
## 1. Configuration
You can configure Netcore Smartech by following the below steps:
1. Enabling the Integration in yellow.ai Integrations Module.
* Login to cloud.yellow.ai and click on the Integrations Module from the top left corner of your screen.
* Then search for the integration named Netcore or choose the category named Tools & Utilities from the left navigation bar and then click on Netcore Smartech.
* Click on Connect and the Integration will be enabled at yellow.ai’s end and the event will be added to Event Hub.
* If you have multiple accounts, follow the above mentioned steps to add each of them.
:::note
1. Enter a unique name for each account to easily identify them within the yellow.ai platform. It is recommended to use a name that aligns with its purpose for better usability.
2. You can add a maximum of 15 accounts.
3. In a two-tier environment, such as bots with only Development/Live environments, you can add account names only in the development mode. Once added and flows have been built, in the Live mode, you can only choose the account names and not edit them.
4. In a three-tier environment, such as bots with Staging/Sandbox/Production modes, in Staging and Sandbox modes, you can add and edit new accounts. However, in Production, only the account details added in Staging will be available. You can only map in the production environment.
:::
****
****
****
2. Configure webhook URL in netcore dashboard.
* Copy the webhook URL mentioned in the Instructions section of the Netcore Smartech Integration Card. Please note that based on the region of your bot i.e r1/r2/r3/r4/r5, you need to append that to the domain of the webhook URL. For example, if the domain is https://cloud.yellow.ai, you need to change it to https://r1.cloud.yellow.ai if the region of the bot is r1. If the bot belongs to the India region, you can use the origin domain itself.
* The client needs to log in to the Netcore Smartech dashboard and navigate to the Webhook URL Configuration section and add the provided webhook URL.
3. Receiving event in yellow.ai Bot.
* Login to cloud.yellow.ai and click on the Automation Module from the top left corner of your screen.
* Click on the Event, from the left navigation bar and then choose Integrations.
* You will find an event named netcoreEvent that needs to be activated by clicking on the three dots next to the name of the event.
* After activating the event, a flow needs to be created in the Automation module whose trigger point is this event. Now based on the event data received, an appropriate message is displayed to the end user.
:::info
If you have added multiple accounts in your platform, enable events for each of those accounts.
:::
****
****
****
Sample webhook event data sent by Paytm:
```
{
"webhook_name": "yellow-ai",
"event_params": {
"foreignkey": "9999999997",
"linkid": -1
},
"custom_params": {
"channel": "sms",
"type": "click"
},
"att_params": {
"MBR_DOBIRTH": "23-12-88",
"AGE_BUCKET_APR17": "25 To <30_Yr",
"MARIAL_STATUS": "S",
"CAMPAINGENAME": "XYZ"
}
}
```
---
## Nice Incontact
Yellow.ai's integration with Nice Incontact allows you to seamlessly connect your Nice Incontact account with the yellow.ai platform. Any customer who has a Nice Incontact account can connect their service with yellow.ai. This connector will connect end users to live agents.
## 1. Configure
1. Inside your project, navigate to **Configuration** and click **Integrations**.
2. Search for **Nice Incontact**.
3. Provide the **Host URL**, **Client Id**, **Client Secret**, **Point of Contact**, **Brand**, **Agent inactivity timeout details** and click **connect**.
4. If you have multiple accounts, follow the above mentioned steps to add each of them.
:::note
1. Enter a unique name for each account to easily identify them within the yellow.ai platform. It is recommended to use a name that aligns with its purpose for better usability.
2. You can add a maximum of 15 accounts.
3. In a two-tier environment, such as bots with only Development/Live environments, you can add account names only in the development mode. Once added and flows have been built, in the Live mode, you can only choose the account names and not edit them.
4. In a three-tier environment, such as bots with Staging/Sandbox/Production modes, in Staging and Sandbox modes, you can add and edit new accounts. However, in Production, only the account details added in Staging will be available. You can only map in the production environment.
5. Only text is being supported from both the user and agent side.
:::
## 2. Use-case
In this integration, you can use the **Raise ticket** node to create a conversation with Nice Incontact and once the conversation gets initiated, the user can talk to the Nice Incontact agent. After the conversation ends, bot takes over the conversation with the user.
:::info
Use **Ticket-closed** in the **Raise Ticket node** to perform specific actions when a live chat closes, instead of using the **ticket-close** event.
:::
:::note
When multiple accounts are added, select the appropriate account for each node, allowing you to leverage the unique functionalities of each account for their intended purposes.
:::
**Reference**
[Nice Incontact](https://developer.niceincontact.com/API/PatronAPI)
---
## Okta Management
Yellow.ai's integration with Okta Management allows you to connect your Okta account directly to your agent, enabling it to perform real-time identity and access management operations — from creating and managing users and groups to handling MFA factors, app assignments, and audit logs — without leaving the conversation.
:::tip What can you build with this?
Common use cases include an **IT helpdesk agent** (unlock accounts, reset passwords, expire credentials), an **onboarding/offboarding agent** (create users, assign apps, deactivate accounts), and an **access management agent** (add users to groups, manage MFA factors, view audit logs).
:::
## Supported Actions
| Action | Description |
| -------- | -------- |
| [Create User](#create-user) | Creates a new user in Okta. |
| [Get User](#get-user) | Fetches a user's profile by ID or login. |
| [Update User](#update-user) | Updates profile fields for an existing user. |
| [Delete User](#delete-user) | Deactivates and deletes a user from Okta. |
| [Activate User](#activate-user) | Activates a staged or deactivated user. |
| [Deactivate User](#deactivate-user) | Deactivates an active user. |
| [Suspend User](#suspend-user) | Suspends an active user. |
| [Unsuspend User](#unsuspend-user) | Restores a suspended user to active status. |
| [Unlock User](#unlock-user) | Unlocks a user who has been locked out. |
| [Reset Password](#reset-password) | Triggers a password reset for a user. |
| [Expire Password](#expire-password) | Expires a user's current password, forcing a change on next login. |
| [Change Password](#change-password) | Changes a user's password using their old and new passwords. |
| [Create Group](#create-group) | Creates a new group in Okta. |
| [Get Group](#get-group) | Fetches a group's details by ID. |
| [Update Group](#update-group) | Updates the name or description of an existing group. |
| [Delete Group](#delete-group) | Deletes a group from Okta. |
| [List Groups](#list-groups) | Lists all groups, with optional search and limit. |
| [Add User to Group](#add-user-to-group) | Assigns a user to a group. |
| [Remove User from Group](#remove-user-from-group) | Removes a user from a group. |
| [Get Application](#get-application) | Fetches details of an Okta application by ID. |
| [Assign App to User](#assign-app-to-user) | Assigns an application to a user. |
| [Unassign App from User](#unassign-app-from-user) | Removes an application assignment from a user. |
| [List Factors](#list-factors) | Lists all MFA factors enrolled for a user. |
| [Enroll Factor](#enroll-factor) | Enrolls a new MFA factor for a user. |
| [Reset Factor](#reset-factor) | Deletes an enrolled MFA factor so a user can re-enroll. |
| [Get Audit Logs](#get-audit-logs) | Retrieves system log events with optional filters and date range. |
| [Get Pending Approvals](#get-pending-approvals) | Lists users in a group (useful for approval queue flows). |
---
## Integrating Okta Management with Yellow.ai
In a two-tier environment, you can connect an integration app in the Development environment. In a three-tier environment, you can connect the integration app either in Staging or Sandbox. All connected integrations are available in the live environment.
To integrate Yellow.ai with Okta Management, follow the steps below:
1. Switch to the Development/Staging environment and go to **Extensions** > **Integrations** > **Tools** > **Okta Management**. Alternatively, use the Search box to quickly find the required integration.
2. In **Give account name**, enter a unique name for the integration. You can use only lowercase alphanumeric characters and underscores (_).
3. Enter your **Domain URL**. This is your Okta org URL, for example: `https://dev-12345.okta.com`.
4. Enter your **API Token**. To generate one, log in to the Okta Admin Console, go to **Security** > **API** > **Tokens**, click **Create Token**, and copy the token value here.
:::note
The API token must have admin privileges to manage users and groups.
:::
5. Click **Connect**.
6. To connect another account, click **+Add Account** and repeat the steps above. You can add a maximum of 15 accounts.
---
## Accessing Okta Management Functions via Agent Flow
Once integrated, you can drop Okta Management action nodes anywhere in your agent flows.
1. Go to **Automation** and create or open a flow that suits your use case.
2. Navigate to the point in the conversation where you want to add the node. Click **Add Node**, then go to **Integrations** and select **Okta Management**.
:::note
When multiple accounts are connected, select the appropriate account for each node. This lets you route different actions through different Okta accounts within the same agent.
:::
---
## Action Nodes
### Create User
Creates a new user record in Okta. You can optionally activate the user immediately upon creation.
**Required parameters:**
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| First Name | String | User's first name. |
| Last Name | String | User's last name. |
| Email | String | User's primary email address. |
| Login (Email) | String | The login identifier — typically the same as the email. |
**Optional parameters:**
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| Mobile Phone | String | User's mobile phone number. |
| Secondary Email | String | An alternate email address. |
| Activate User | Boolean | Set to `true` to activate the user immediately upon creation. Defaults to `false`. |
**Sample response:**
```json
{
"id": "00ub0oNGTSWTBKOLGLNR",
"status": "STAGED",
"created": "2024-01-15T10:30:00.000Z",
"activated": null,
"lastLogin": null,
"lastUpdated": "2024-01-15T10:30:00.000Z",
"passwordChanged": null,
"profile": {
"firstName": "Jordan",
"lastName": "Lee",
"email": "jordan.lee@example.com",
"login": "jordan.lee@example.com",
"mobilePhone": "+1-555-123-4567",
"secondEmail": null
},
"credentials": {
"provider": {
"type": "OKTA",
"name": "OKTA"
}
}
}
```
> 📖 [Okta API Reference — Create User](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/User/#tag/User/operation/createUser)
---
### Get User
Fetches the full profile of a user by their Okta User ID or login (email).
**Required parameters:**
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| Search By | String | Choose to look up the user by `User ID` or `Login (Email)`. |
| Search Value | String | The actual ID or login value to search for. |
**Sample response:**
```json
{
"id": "00ub0oNGTSWTBKOLGLNR",
"status": "ACTIVE",
"created": "2024-01-15T10:30:00.000Z",
"activated": "2024-01-15T10:35:00.000Z",
"lastLogin": "2024-05-20T08:12:00.000Z",
"lastUpdated": "2024-05-20T08:12:00.000Z",
"passwordChanged": "2024-02-01T09:00:00.000Z",
"profile": {
"firstName": "Jordan",
"lastName": "Lee",
"email": "jordan.lee@example.com",
"login": "jordan.lee@example.com",
"mobilePhone": "+1-555-123-4567",
"secondEmail": null
},
"credentials": {
"password": {},
"provider": {
"type": "OKTA",
"name": "OKTA"
}
}
}
```
> 📖 [Okta API Reference — Get User](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/User/#tag/User/operation/getUser)
---
### Update User
Updates one or more profile fields for an existing user. Only the fields you pass will be changed — all others remain untouched.
**Required parameters:**
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| User ID or Login | String | The Okta User ID or login of the user to update. |
**Optional parameters:**
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| First Name | String | Updated first name. |
| Last Name | String | Updated last name. |
| Email | String | Updated email address. |
| Mobile Phone | String | Updated mobile phone number. |
| Secondary Email | String | Updated secondary email address. |
**Sample response:**
```json
{
"id": "00ub0oNGTSWTBKOLGLNR",
"status": "ACTIVE",
"created": "2024-01-15T10:30:00.000Z",
"lastUpdated": "2024-05-29T11:00:00.000Z",
"profile": {
"firstName": "Jordan",
"lastName": "Lee-Smith",
"email": "jordan.leesmith@example.com",
"login": "jordan.lee@example.com",
"mobilePhone": "+1-555-999-8888",
"secondEmail": "jlee@personal.com"
}
}
```
> 📖 [Okta API Reference — Update User](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/User/#tag/User/operation/updateUser)
---
### Delete User
Deactivates and permanently removes a user from Okta. Optionally sends a notification email to the user upon deletion.
**Required parameters:**
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| User ID or Login | String | The Okta User ID or login of the user to delete. |
**Optional parameters:**
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| Send Email | Boolean | Set to `true` to send the user a notification email upon deletion. |
**Sample response:**
```json
{
"status": 204,
"message": "User successfully deactivated and deleted."
}
```
:::note
A successful delete returns HTTP `204 No Content`. The response body is empty on success. The sample above is a Yellow.ai wrapper response for display in the agent flow.
:::
:::warning
This action is irreversible — ensure your flow includes a confirmation step before executing.
:::
> 📖 [Okta API Reference — Delete User](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/User/#tag/User/operation/deactivateUser)
---
### Activate User
Activates a user who is in `STAGED` or `DEPROVISIONED` status. Optionally sends an activation email with a link to set up their account.
**Required parameters:**
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| User ID | String | The Okta User ID of the user to activate. |
**Optional parameters:**
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| Send Email | Boolean | Set to `true` to send the activation email to the user. |
**Sample response:**
```json
{
"activationUrl": "https://dev-12345.okta.com/welcome/XE6wE17zmphl3KqAPFxO",
"activationToken": "XE6wE17zmphl3KqAPFxO"
}
```
:::note
`activationUrl` is only returned when `Send Email` is `false`. When `Send Email` is `true`, Okta sends the link directly to the user and the response body is empty.
:::
> 📖 [Okta API Reference — Activate User](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/User/#tag/User/operation/activateUser)
---
### Deactivate User
Deactivates an active user, transitioning their status to `DEPROVISIONED`. The user loses all access to Okta apps and services.
**Required parameters:**
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| User ID | String | The Okta User ID of the user to deactivate. |
**Sample response:**
```json
{
"status": 200,
"message": "User successfully deactivated.",
"userId": "00ub0oNGTSWTBKOLGLNR",
"userStatus": "DEPROVISIONED"
}
```
> 📖 [Okta API Reference — Deactivate User](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/User/#tag/User/operation/deactivateUser)
---
### Suspend User
Suspends an active user. A suspended user cannot sign in but their account and data are preserved. Useful for temporary offboarding or security holds.
**Required parameters:**
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| User ID | String | The Okta User ID of the user to suspend. |
**Sample response:**
```json
{
"status": 200,
"message": "User successfully suspended.",
"userId": "00ub0oNGTSWTBKOLGLNR",
"userStatus": "SUSPENDED"
}
```
> 📖 [Okta API Reference — Suspend User](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/User/#tag/User/operation/suspendUser)
---
### Unsuspend User
Restores a suspended user back to `ACTIVE` status, re-enabling their login access.
**Required parameters:**
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| User ID | String | The Okta User ID of the user to unsuspend. |
**Sample response:**
```json
{
"status": 200,
"message": "User successfully unsuspended.",
"userId": "00ub0oNGTSWTBKOLGLNR",
"userStatus": "ACTIVE"
}
```
> 📖 [Okta API Reference — Unsuspend User](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/User/#tag/User/operation/unsuspendUser)
---
### Unlock User
Unlocks a user account that has been locked out due to too many failed sign-in attempts, restoring their ability to log in.
**Required parameters:**
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| User ID | String | The Okta User ID of the user to unlock. |
**Sample response:**
```json
{
"status": 200,
"message": "User successfully unlocked.",
"userId": "00ub0oNGTSWTBKOLGLNR",
"userStatus": "ACTIVE"
}
```
> 📖 [Okta API Reference — Unlock User](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/User/#tag/User/operation/unlockUser)
---
### Reset Password
Triggers a password reset for a user. If `Send Email` is enabled, the user receives a reset link via email. Otherwise, the reset URL is returned in the response for admin use.
**Required parameters:**
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| User ID | String | The Okta User ID of the user whose password should be reset. |
**Optional parameters:**
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| Send Email | Boolean | Set to `true` to send the password reset email to the user. Set to `false` to return the reset URL in the response instead. |
**Sample response:**
```json
{
"resetPasswordUrl": "https://dev-12345.okta.com/reset_password/XE6wE17zmphl3KqAPFxO"
}
```
:::note
`resetPasswordUrl` is only returned when `Send Email` is `false`. When `Send Email` is `true`, Okta delivers the link directly to the user and the response body is empty.
:::
> 📖 [Okta API Reference — Reset Password](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/User/#tag/User/operation/resetPassword)
---
### Expire Password
Expires a user's current password immediately. On their next login, the user will be forced to set a new password. Returns a temporary password that can be shared with the user if needed.
**Required parameters:**
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| User ID | String | The Okta User ID of the user whose password should be expired. |
**Sample response:**
```json
{
"tempPassword": {
"value": "TmpP@ssw0rd123"
}
}
```
> 📖 [Okta API Reference — Expire Password](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/User/#tag/User/operation/expirePassword)
---
### Change Password
Changes a user's password by verifying their current password and setting a new one. Both the old and new passwords must be provided.
**Required parameters:**
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| User ID | String | The Okta User ID of the user. |
| Old Password | Object | An object with a `value` field containing the user's current password. |
| New Password | Object | An object with a `value` field containing the desired new password. |
**Sample response:**
```json
{
"credentials": {
"password": {},
"provider": {
"type": "OKTA",
"name": "OKTA"
}
}
}
```
:::note
A successful change returns the updated credentials object. The password field is always returned as an empty object `{}` — Okta never exposes actual password values in responses.
:::
> 📖 [Okta API Reference — Change Password](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/User/#tag/User/operation/changePassword)
---
### Create Group
Creates a new Okta group with a name and optional description. Groups are used to manage app assignments, policies, and access control at scale.
**Required parameters:**
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| Group Name | String | The display name for the new group. |
**Optional parameters:**
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| Description | String | A short description of the group's purpose. |
**Sample response:**
```json
{
"id": "00g1emaKYZTWRYYRRTSK",
"created": "2024-01-15T10:30:00.000Z",
"lastUpdated": "2024-01-15T10:30:00.000Z",
"lastMembershipUpdated": "2024-01-15T10:30:00.000Z",
"type": "OKTA_GROUP",
"profile": {
"name": "Engineering Team",
"description": "All engineering department employees"
},
"objectClass": ["okta:user_group"]
}
```
> 📖 [Okta API Reference — Create Group](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/Group/#tag/Group/operation/createGroup)
---
### Get Group
Fetches the details of an Okta group using its Group ID.
**Required parameters:**
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| Group ID | String | The unique ID of the group to retrieve. |
**Sample response:**
```json
{
"id": "00g1emaKYZTWRYYRRTSK",
"created": "2024-01-15T10:30:00.000Z",
"lastUpdated": "2024-05-20T08:00:00.000Z",
"lastMembershipUpdated": "2024-05-18T14:22:00.000Z",
"type": "OKTA_GROUP",
"profile": {
"name": "Engineering Team",
"description": "All engineering department employees"
},
"objectClass": ["okta:user_group"]
}
```
> 📖 [Okta API Reference — Get Group](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/Group/#tag/Group/operation/getGroup)
---
### Update Group
Updates the name and/or description of an existing Okta group.
**Required parameters:**
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| Group ID | String | The unique ID of the group to update. |
| Group Name | String | The new name for the group. |
**Optional parameters:**
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| Description | String | Updated description for the group. |
**Sample response:**
```json
{
"id": "00g1emaKYZTWRYYRRTSK",
"created": "2024-01-15T10:30:00.000Z",
"lastUpdated": "2024-05-29T11:45:00.000Z",
"lastMembershipUpdated": "2024-05-18T14:22:00.000Z",
"type": "OKTA_GROUP",
"profile": {
"name": "Engineering Team - Backend",
"description": "Backend engineering team members"
}
}
```
> 📖 [Okta API Reference — Update Group](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/Group/#tag/Group/operation/replaceGroup)
---
### Delete Group
Permanently deletes an Okta group. This does not delete the users who were members of the group.
**Required parameters:**
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| Group ID | String | The unique ID of the group to delete. |
**Sample response:**
```json
{
"status": 204,
"message": "Group successfully deleted."
}
```
:::note
A successful delete returns HTTP `204 No Content`. The response body is empty on success. The sample above is a Yellow.ai wrapper response.
:::
:::warning
This action is irreversible — ensure your flow includes a confirmation step before executing.
:::
> 📖 [Okta API Reference — Delete Group](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/Group/#tag/Group/operation/deleteGroup)
---
### List Groups
Returns a list of all groups in your Okta org. Supports an optional search query and result limit.
**Optional parameters:**
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| Search Query | String | A search string to filter groups by name. |
| Limit | Number | Maximum number of groups to return. |
**Sample response:**
```json
[
{
"id": "00g1emaKYZTWRYYRRTSK",
"created": "2024-01-15T10:30:00.000Z",
"lastUpdated": "2024-05-20T08:00:00.000Z",
"lastMembershipUpdated": "2024-05-18T14:22:00.000Z",
"type": "OKTA_GROUP",
"profile": {
"name": "Engineering Team",
"description": "All engineering department employees"
}
},
{
"id": "00g2xyzABCTWRYYRRXYZ",
"created": "2024-02-01T09:00:00.000Z",
"lastUpdated": "2024-05-10T07:30:00.000Z",
"lastMembershipUpdated": "2024-05-10T07:30:00.000Z",
"type": "OKTA_GROUP",
"profile": {
"name": "HR Team",
"description": "Human resources team"
}
}
]
```
> 📖 [Okta API Reference — List Groups](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/Group/#tag/Group/operation/listGroups)
---
### Add User to Group
Assigns an existing Okta user to a group. Both the User ID and Group ID are required.
**Required parameters:**
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| Group ID | String | The unique ID of the target group. |
| User ID | String | The unique ID of the user to add. |
**Sample response:**
```json
{
"status": 204,
"message": "User successfully added to group.",
"userId": "00ub0oNGTSWTBKOLGLNR",
"groupId": "00g1emaKYZTWRYYRRTSK"
}
```
:::note
A successful add returns HTTP `204 No Content`. The response body is empty on success. The sample above is a Yellow.ai wrapper response.
:::
> 📖 [Okta API Reference — Add User to Group](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/Group/#tag/Group/operation/assignUserToGroup)
---
### Remove User from Group
Removes an Okta user from a group. The user account itself is not affected.
**Required parameters:**
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| Group ID | String | The unique ID of the group. |
| User ID | String | The unique ID of the user to remove. |
**Sample response:**
```json
{
"status": 204,
"message": "User successfully removed from group.",
"userId": "00ub0oNGTSWTBKOLGLNR",
"groupId": "00g1emaKYZTWRYYRRTSK"
}
```
:::note
A successful removal returns HTTP `204 No Content`. The response body is empty on success. The sample above is a Yellow.ai wrapper response.
:::
> 📖 [Okta API Reference — Remove User from Group](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/Group/#tag/Group/operation/unassignUserFromGroup)
---
### Get Application
Fetches the details of an Okta application using its Application ID. Returns the app's name, label, current status, sign-on mode, and settings.
**Required parameters:**
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| Application ID | String | The unique ID of the Okta application to retrieve. |
**Sample response:**
```json
{
"id": "0oabkvBLDEKCNXBMBWKR",
"name": "template_saml_2_0",
"label": "Sample SAML App",
"status": "ACTIVE",
"created": "2023-06-01T08:00:00.000Z",
"lastUpdated": "2024-05-15T10:00:00.000Z",
"signOnMode": "SAML_2_0",
"settings": {
"app": {
"audienceRestriction": "https://www.example.com/audience",
"postBackURL": "https://www.example.com/sso/saml"
}
}
}
```
> 📖 [Okta API Reference — Get Application](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/Application/#tag/Application/operation/getApplication)
---
### Assign App to User
Assigns an Okta application to a specific user, granting them access to that app.
**Required parameters:**
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| Application ID | String | The unique ID of the application to assign. |
| User ID | String | The unique ID of the user to assign the application to. |
**Optional parameters:**
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| Assignment Scope | String | The scope of the assignment (e.g., `USER`). |
**Sample response:**
```json
{
"id": "00u15s1KDETTQMQYABRL",
"externalId": null,
"created": "2024-05-29T11:00:00.000Z",
"lastUpdated": "2024-05-29T11:00:00.000Z",
"scope": "USER",
"status": "ACTIVE",
"syncState": "DISABLED",
"credentials": {
"userName": "jordan.lee@example.com"
}
}
```
> 📖 [Okta API Reference — Assign App to User](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/Application/#tag/Application/operation/assignUserToApplication)
---
### Unassign App from User
Removes an application assignment from a user, revoking their access to that app.
**Required parameters:**
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| Application ID | String | The unique ID of the application. |
| User ID | String | The unique ID of the user to unassign. |
**Sample response:**
```json
{
"status": 204,
"message": "Application successfully unassigned from user.",
"userId": "00ub0oNGTSWTBKOLGLNR",
"appId": "0oabkvBLDEKCNXBMBWKR"
}
```
:::note
A successful unassignment returns HTTP `204 No Content`. The response body is empty on success. The sample above is a Yellow.ai wrapper response.
:::
> 📖 [Okta API Reference — Unassign App from User](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/Application/#tag/Application/operation/unassignUserFromApplication)
---
### List Factors
Returns all MFA factors currently enrolled for a user, including their type, provider, and activation status. Use this node to retrieve a `factorId` before calling Reset Factor.
**Required parameters:**
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| User ID | String | The unique ID of the user whose factors to list. |
**Sample response:**
```json
[
{
"id": "ufs2bysphxKODSZKWVCT",
"factorType": "token:software:totp",
"provider": "GOOGLE",
"status": "ACTIVE",
"created": "2024-01-20T09:00:00.000Z",
"lastUpdated": "2024-01-20T09:00:00.000Z",
"profile": {
"credentialId": "jordan.lee@example.com"
}
},
{
"id": "sms2gt8gzgEBPUWBIFHN",
"factorType": "sms",
"provider": "OKTA",
"status": "ACTIVE",
"created": "2024-01-21T10:00:00.000Z",
"lastUpdated": "2024-01-21T10:00:00.000Z",
"profile": {
"phoneNumber": "+1-555-123-4567"
}
}
]
```
> 📖 [Okta API Reference — List Factors](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/UserFactor/#tag/UserFactor/operation/listFactors)
---
### Enroll Factor
Enrolls a new MFA factor for a user. Requires specifying the factor type and provider. The factor will be in `PENDING_ACTIVATION` status until the user completes verification.
**Required parameters:**
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| User ID | String | The unique ID of the user to enroll a factor for. |
| Factor Type | String | The type of factor to enroll (e.g., `token:software:totp`, `sms`). |
| Provider | String | The factor provider (e.g., `GOOGLE`, `OKTA`). |
**Sample response:**
```json
{
"id": "uftm3iHSGFQXHCUSDAND",
"factorType": "token:software:totp",
"provider": "GOOGLE",
"status": "PENDING_ACTIVATION",
"created": "2024-05-29T11:30:00.000Z",
"lastUpdated": "2024-05-29T11:30:00.000Z",
"profile": {
"credentialId": "jordan.lee@example.com"
},
"_embedded": {
"activation": {
"timeStep": 30,
"sharedSecret": "JBSWY3DPEHPK3PXP",
"encoding": "base32",
"keyLength": 6,
"qrcode": {
"href": "https://dev-12345.okta.com/api/v1/users/00ub0oNGTSWTBKOLGLNR/factors/uftm3iHSGFQXHCUSDAND/qr/00fukNElRS_Tz6k-CFhg3pH4KO2dj2guhmaapXWbc4",
"type": "image/png"
}
}
}
}
```
> 📖 [Okta API Reference — Enroll Factor](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/UserFactor/#tag/UserFactor/operation/enrollFactor)
---
### Reset Factor
Deletes a specific enrolled MFA factor for a user, allowing them to re-enroll. Use this when a user loses their phone or needs to reset their authenticator app. Call [List Factors](#list-factors) first to obtain the `factorId`.
**Required parameters:**
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| User ID | String | The ID of the user whose factor you want to reset. |
| Factor ID | String | The ID of the specific MFA factor to delete. Obtained from List Factors. |
**Sample response:**
```json
{
"status": 204,
"message": "MFA factor successfully deleted. The user can now re-enroll.",
"userId": "00ub0oNGTSWTBKOLGLNR",
"factorId": "ufs2bysphxKODSZKWVCT"
}
```
:::note
A successful reset returns HTTP `204 No Content`. The response body is empty on success. The sample above is a Yellow.ai wrapper response.
:::
> 📖 [Okta API Reference — Reset Factor](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/UserFactor/#tag/UserFactor/operation/deleteFactor)
---
### Get Audit Logs
Retrieves system log events from Okta, with optional date range filtering, custom filter expressions, and result limits. Useful for security audits, compliance checks, or building an activity-monitoring agent.
**Optional parameters:**
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| Since | String (ISO date) | Start of the date range to query (e.g., `2026-01-01T00:00:00Z`). |
| Until | String (ISO date) | End of the date range to query. |
| Filter | String | An SCIM filter expression to narrow results (e.g., by event type). |
| Limit | Number | Maximum number of log entries to return. |
**Sample response:**
```json
[
{
"actor": {
"id": "00ub0oNGTSWTBKOLGLNR",
"type": "User",
"alternateId": "admin@example.com",
"displayName": "Admin User"
},
"client": {
"ipAddress": "203.0.113.42",
"geographicalContext": {
"city": "Bangalore",
"country": "India"
}
},
"eventType": "user.session.start",
"outcome": {
"result": "SUCCESS"
},
"published": "2026-05-29T08:12:00.000Z",
"severity": "INFO",
"target": [
{
"id": "00ub0oNGTSWTBKOLGLNR",
"type": "User",
"alternateId": "jordan.lee@example.com",
"displayName": "Jordan Lee"
}
]
}
]
```
> 📖 [Okta API Reference — Get Audit Logs](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/SystemLog/#tag/SystemLog/operation/listLogEvents)
---
### Get Pending Approvals
Lists all users currently in a specified group. Useful for building approval queue or access-request workflows where a group represents users awaiting review.
**Required parameters:**
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| Group ID | String | The unique ID of the group to list members for. |
**Optional parameters:**
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| Limit | Number | Maximum number of users to return. |
**Sample response:**
```json
[
{
"id": "00ub0oNGTSWTBKOLGLNR",
"status": "ACTIVE",
"created": "2024-01-15T10:30:00.000Z",
"activated": "2024-01-15T10:35:00.000Z",
"lastLogin": "2026-05-28T09:00:00.000Z",
"lastUpdated": "2026-05-28T09:00:00.000Z",
"profile": {
"firstName": "Jordan",
"lastName": "Lee",
"email": "jordan.lee@example.com",
"login": "jordan.lee@example.com"
}
},
{
"id": "00uc1pExGOQAVXZSMATP",
"status": "ACTIVE",
"created": "2024-03-10T08:00:00.000Z",
"activated": "2024-03-10T08:05:00.000Z",
"lastLogin": "2026-05-27T11:00:00.000Z",
"lastUpdated": "2026-05-27T11:00:00.000Z",
"profile": {
"firstName": "Priya",
"lastName": "Sharma",
"email": "priya.sharma@example.com",
"login": "priya.sharma@example.com"
}
}
]
```
> 📖 [Okta API Reference — List Group Users](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/Group/#tag/Group/operation/listGroupUsers)
---
## Error Reference
All Okta Management action nodes return structured errors. The following codes may appear in the agent's error path:
| Error Status | Code | HTTP Status | What it means | How to fix |
| ------------ | ---- | ----------- | ------------- | ---------- |
| `INVALID_FIELD_VALUE` | 8001 | 400 | One or more parameters are missing, the wrong type, or incorrectly formatted. | Check that all required fields are present and values are valid. |
| `AUTHENTICATION_FAILURE` | 8002 | 401 | The API token is invalid, expired, or missing. | Regenerate the API token in Okta under **Security** > **API** > **Tokens** and update it in your Yellow.ai integration config. |
| `RESOURCE_NOT_FOUND` | 8002–8003 | 404 | The specified user, group, application, or factor does not exist. | Verify that the ID or login value is correct and the resource exists in Okta. |
| `DUPLICATE_USER` | 8003 | 409 | A user already exists with the provided login. | Check for an existing account with the same login before creating a new one. |
| `RESOURCE_ACCESS_DENIED` | 9001 | 403 | The API token does not have permission to perform this action. | Check the token's admin scope in the Okta Admin Console under **Security** > **API**. |
| `API_LIMIT_REACHED` | 9002 | 429 | The Okta API rate limit has been reached. | Reduce the frequency of requests or implement retry logic with backoff in your agent flow. |
---
## Related Resources
- [Okta Management API Documentation](https://developer.okta.com/docs/api/)
- [Okta — Managing API Tokens](https://developer.okta.com/docs/guides/create-an-api-token/)
- [Okta — User Lifecycle Overview](https://developer.okta.com/docs/concepts/user-lifecycles/)
- [Okta — Groups API Reference](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/Group/)
- [Okta — System Log API Reference](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/SystemLog/)
---
## Okta Integration
Your Yellow.ai platform can now be integrated with [Okta](https://www.okta.com/). **Okta** is a customizable, secure, and drop-in solution that adds authentication and authorization services to your applications. Get scalable authentication built right into your application without the development overhead, security risks, and maintenance that come from building it yourself.
You can connect any application in any language or on any stack to Okta and define how you want your users to sign in. Each time a user tries to authenticate, **Okta** will verify their identity and send the required information back to your app. This integration lets you generate login links and get user details.
## 1. Connect Yellow.ai with Okta
To connect your Okta account with Yellow.ai, follow the steps mentioned below:
### 1.1 Fetch Okta app integration credentials
1. Sign-in to your **Okta** with your Admin account. In the **Admin Console**, go to **Applications** > **Applications**.
2. If you already have the app integration in your org, you can search for it using the search box. Once you find it, click on it to go to the settings page. [OR] Use **Browse App Catalog** to choose a preconfigured app integration in the **Okta** catalog.
:::note
* For Single Sign-On (SAML) apps, the Client ID is not applicable or visible.
:::
3. Once you click the app integration, you will be redirected to the setting page. Here, under the **General** tab, the **Client Credentials** section shows the **Client ID** and **Client secrets** for your app integration.
You can copy the **Client ID** and **Client secret values** using the Copy to Clipboard button beside each text field.
:::note
* In **Grant type** please select **Client credentials** and **Authorization code**.
* In redirectUri, please add the webhook URL copied from integration card.
* Ensure that you have selected the user consent.
:::
### 1.2 Enable the integration in Yellow.ai
1. On the left navigation bar, go to **Extensions** > **Integrations**.
3. In **Tools & utilities**, select **Okta**. You can also search for the **Okta**.
5. Fill in the fields under **Account Details** and click **Connect**.
6. If you have multiple accounts, follow the above-mentioned steps to add each of them.
:::note
1. Enter a unique name for each account to easily identify them within the yellow.ai platform. It is recommended to use a name that aligns with its purpose for better usability.
2. You can add a maximum of 15 accounts.
3. In a two-tier environment, such as bots with only Development/Live environments, you can add account names only in the development mode. Once added and flows have been built, in the Live mode, you can only choose the account names and not edit them.
4. In a three-tier environment, such as bots with Staging/Sandbox/Production modes, in Staging and Sandbox modes, you can add and edit new accounts. However, in Production, only the account details added in Staging will be available. You can only map in the production environment.
:::
### 1.3 Receive event in Yellow.ai bot
1. In the left navigation, go to **Automation** > **Events**.
2. Click on **Custom Events**.
5. Create an event named **okta-auth-success** and activate it.
6. A journey needs to be created in the Automation module with this event as its trigger point. Based on the received event data, an appropriate message will be displayed to the end user.
:::info
If you have added multiple accounts in your platform, enable events for each of those accounts.
:::
## 2. Use-Cases
The following use-cases are accommodated in this integration.
:::note
When multiple accounts are added, select the appropriate account for each node, allowing you to leverage the unique functionalities of each account for their intended purposes.
:::
### 2.1 Generate login link
1. In the [Automation flow builder](https://docs.yellow.ai/docs/platform_concepts/studio/build/Flows/journeys), choose the node type as **Integrations** and select **Okta** from the list of integrations that have been enabled for that particular bot. An **Integration Action Node** will be added to the flow builder.
3. When you click the **Integration Action Node**, a drop-down of all the available use-cases for this integration will be displayed. Click **Generate Login URL** from that dropdown.
5. Fill in the following field for the execution of the use-case. The following is a table that consists of the sample value, data type and description for each of these fields.
| Field name | Sample value | Data type |Description|
| -------- | -------- | -------- |----|
| Redirect URI | `https://cloud.yellow.ai/integrations/genericIntegration/oauth/okta/x5` | String | Callback location where the authorization code or tokens should be sent. It must match the value that was pre-registered in Okta during the client registration. Copy the value from integration card and pass it here.|
|Scope| openid profile | String | ID tokens and access tokens can access openid, profile, email, address, phone, offline_access, and groups.|
5. The **Generate Login URL Integration Action Node** has two outcomes, success or failure. Based on the success/failure of the execution of the **Integration Action Node**, the flow will proceed to success or fallback branches respectively.
**Sample response in case of success:**
```
{
"success": true,
"message": "Login URL Generated Successfully.",
"data": {
"oktaLoginUrl": "https://login.microsoftonline.com/JDVE/oauth2/v2.0/authorize?client_id=ABXS&response_type=code&redirect_uri=https://app.yellowmessenger.com/integrations/azureauth/&response_mode=query&state=eyJib3QiOiJ4MTY0NTQzMDgyNTY0NSIsInNvdXJjZSI6IlVjaGloYSIsInNlbmRlciI6IjIxODQ5ODMzNTIzNDA0MTQ3MjA4NzE3NjYxMl8yMTg0OTgzMzUyMzQwNDE0NzIwODcxNzY2MTJfV3BjbkYxRlEyZ2lqcTdUdGYwMEJQIn0=&scope=BESB"
}
}
```
To use this **Integration Action Node** in an app.yellow.ai bot, refer to the following example:
```
app.executeIntegrationAction({
"integrationName": "okta",
"action": "Generate Login URL",
"dynamicParams": {
"redirectUri": "https://cloud.yellow.ai/integrations/genericIntegration/oauth/okta/x1632218421575",
"scope": "openid profile email"
}
}).then((res) => {
console.log("response from action node", res);
app.log(res, '||Response from action node||')
}).catch((err) => {
console.log("Error in action node", err);
app.log(err, '||Error in action node||')
})
```
### 2.2 Get user info
1. In the [Automation flow builder](https://docs.yellow.ai/docs/platform_concepts/studio/build/Flows/journeys), choose the node type as **Integrations** and select **Okta** from the list of integrations that have been enabled for that particular bot. An **Integration Action Node** will be added to the flow builder.
3. Once you click the **Integration Action Node**, you will see a dropdown of available use-cases for this integration. Click **Get User Info** from that dropdown.
5. Fill in the following fields for the execution of the use-case. The following is a table that consists of the sample value, data type and description for each of these fields.
| Field name | Sample value | Data type |Description|
| -------- | -------- | -------- |----|
| Access Token | asddskeku2iwewbhwjsnmelsdjckmd22eokeds| String | You will get the access token in OKTA event after successful login.
**Sample response in case of success:**
```
{
"sub": "00uid4BxXw6I6TV4m0g3",
"name" :"John Doe",
"nickname":"Jimmy",
"given_name":"John",
"middle_name":"James",
"family_name":"Doe",
"profile":"https://example.com/john.doe",
"zoneinfo":"America/Los_Angeles",
"locale":"en-US",
"updated_at":1311280970,
"email":"john.doe@example.com",
"email_verified":true,
"address" : { "street_address":"123 Hollywood Blvd.", "locality":"Los Angeles", "region":"CA", "postal_code":"90210", "country":"US" },
"phone_number":"+1 (425) 555-1212"
}
```
To use this **Integration Action Node** in an app.yellow.ai bot, refer to the following example:
```
app.executeIntegrationAction({
"integrationName": "okta",
"action": "Get User Info",
"dynamicParams": {
"accessToken": "youraccessTokenValue"
}
}).then((res) => {
console.log("response from action node", res);
app.log(res, '||Response from action node||')
}).catch((err) => {
console.log("Error in action node", err);
app.log(err, '||Error in action node||')
})
```
---
## Yellow.ai on Oracle Responsys
Yellow.AI integrates with Oracle Responsys to provide valuable opportunities to engage with your leads and contacts on their preferred messaging platform. By harnessing the power of WhatsApp, you can seamlessly run text message and multimedia marketing campaigns through the Oracle Responsys Program Designer.
## Supported features
This integration connects Yellow.ai with Oracle Responsys Program Designer, providing direct control over your WhatsApp business account without the need for additional tools. It empowers businesses to run effective WhatsApp marketing campaigns, automating communication with customers through campaigns at various stages of the marketing and sales funnel.
With shared account access, multiple users can streamline communication, while the media support allows businesses to send visually engaging and informative messages using images, and videos.
## Prerequisites
To run Whatsapp campaigns on yellow.ai via Oracle Responsys, the following prerequisites must be met:
1. An active yellow.ai account
2. An active Oracle Responsys account
3. A WhatsApp Business Account
4. Obtain opt-in from customers to ensure that you have their consent to engage with them. Filtering your audience based on their opt-in status is essential for compliance and respectful messaging. By following these guidelines, you can maintain a positive relationship and trust with your customers while utilizing WhatsApp for effective communication and marketing campaigns.
You can also refer to this video to set up the installation.
## Configure Oracle responsys on Yellow.ai
1. [Sign up](https://docs.yellow.ai/docs/platform_concepts/get_started/account-setup#2-signup-to-yellowai) on cloud.yellow.ai and [create a bot](https://docs.yellow.ai/docs/platform_concepts/get_started/account-setup#21-to-create-a-bot-from-scratch).
2. Enter your Oracle account name in the **Give account name** field and click **Connect**.
3. Copy the **API key**.
4. Go to **Access control** > **API keys** > **Generate new API key**
5. Fill the fields and click **Save**.
6. Copy the API key.
7. Configure WABA number for this bot by following steps mentioned [here](https://docs.yellow.ai/docs/platform_concepts/channelConfiguration/whatsapp-configuration#connect-your-whatsapp-business-account).
8. Set up Whatsapp templates by following steps mentioned [here](https://docs.yellow.ai/docs/platform_concepts/engagement/outbound/templates/whatsapptemplate).
## Install Yellow.ai app on Oracle
1. Go to your Oracle account and go to **Account** > **App management** > **Oracle Marektplace**.
2. Search for Yellow and click **Get App**.
3. Click **Install** in the following pop-up.
4. Fill in the fields and click **Save** and **Proceed**.
* **Template API key:** Copy paste this from Access coontrol (step 4,5,6 from the previous section)
* **GIF API Key:** Copy paste the API key from the Inetgration card (step 1,2 and 3 from the previous section)
5. You will be redirected to your Oracle Responsys account.
6. Go to **Account Management** > **App Management** , search for **Yellow Whatsapp Campaign for Oracle Responsys** to locate the app. If you haven't provided the API keys in the previous section, you can click the edit button and configure them here.
## Configure Whatsapp campaigns on Oracle Responsys
### Step 1: Create a program
1. Go to **Program** and click **Create program**.
2. In the following pop-up, fill in the following fields:
* In **Name**, enter a name for your project.
* In **Folder**, choose a folder for your project.
* In **List**, select a list.
* In **Description**, describe your project and click **Create**.
### Step 2: Create a profile list
Users can create a profile list encompassing all customers, serving as a customer database to define and customize all data requirements. To send customized campaign messages to users, the data added her will be utilized
1. Go to **Data** > **Profile Lists**.
2. Click **Create New List**.
3. Enter a unique name, select the containing folder, and provide a description if required.
5. Click **Save**.
6. To add custom fields, go to **List Information** > **Change Schema**.
7. Click **Add new field** to add new custom fields and click **Save**.
8. To add a new record to this profile list, go to **List Information** > **View Records** > **New Record**.
:::warning
* Mobile number and Opt-in fields should be mandatorily added for the campaign to work.
* Additionally, you have the option to import CSV data and populate the profile list. For more information, please click [here](https://docs.oracle.com/en/cloud/saas/marketing/responsys-user/Connect_WizardUpload.htm).
:::
### Step 3: Create filter
You can create a filter within a profile list, that lets you target customers based on specific characteristics.
1. Go to **Audience** > **Filters**.
2. Click **Create Filter** and select the **Profile List** for which you want he filter to be applied.
3. Select a list from **List Type** and a filter from **Filter Type** and click **Done**.
4. In the following screen, drag and drop the fields to set conditions.
5. Click **Save** and fill in the fields to save the filter.
6. Click **Get actual count** to get the total number of records in that filter.
### Step 4: Use Yellow.ai inside Oracle Responsys
1. Go to **Program** and click the program created in Step 1.
2. Drag and drop **Scheduled filter or view** on the board. Then, click the node and select the audience and time for running this campaign.
> You can also use another entry point for your campaign, **Customer Activated**, executed when a new customer record is created in the program's profile list. Click [here](https://docs.oracle.com/en/cloud/saas/marketing/responsys-user/Programs_Overview.htm) to learn more about it.
3. Drag and drop **Apps** and click it.
4. Choose the Yellow App and click **Done**.
5. Click **Configure App** in the following pop-up.
6. Fill in the following fields:
* In **Registered WABA Numbers**, choose the WABA number from which the campaign should be sent.
* In **To Number**, select the field which contains the data to which the campaign should be sent. Always ensure that the **To** number field is mapped to a designated field that will store your customers' phone numbers in the records.
* In **Template Name**, select the template that should be used for the campiagn.
* Based on the chosen template, map dynamic parameters to the relevant fields in the profile list records. The **To Number** and **Parameter** drop-down menus will display the fields specified during program creation.
7. Click **Save**.
8. To verify the campaign, validate and save the program and then click **Publish** to make it available for your end users.
**Sample Whatsapp campaign:**
---
## MS Outlook Calendar
Yellow.ai integrates with MS Outlook Calendar to make it easy for you to manage your schedule. With this integration, you can create, reschedule, retrieve, and cancel online meetings and events. You can also see when others are free or busy and suggest times that work best for everyone. Lastly, you can attach files to events for easy organization.
## 1. Connect MS Outlook with Yellow.ai
Yellow.ai integrates with the Outlook calendar using the OAuth 2.0 authentication. During integration, Yellow.ai guides you to login page of the Microsoft Identity provider, where you must log in to their work account and provide consent to access their calendar data. Follow the below- mentioned steps to connect your MS Outlook account with your yellow.ai bot.
### 1.1 Register an app on Azure Active Directory
1. Go to portal.azure.com > **Active Directory** > **App Registrations**.
2. Click **New Registration** and provide the details for the new app.
3. To get the Redirect URI details, retrieve the redirect URL from the Outlook Calendar integration card in the Yellow.ai platform integration module. For example, `https://cloud.yellow.ai/integrations/genericIntegration/oauth/outlook-calendar`.
4. Navigate to **Certificates & Secrets** > **New client secret** > Fill the description & select **Expires** to your convenience (recommended 6 months), click **Add** button, a **Client Secret** will be generated, save the value of the Client Secret.
5. Under **API Permissions** > **Add a permission** -> **Select Microsoft Graph** -> **Delegated permission** -> search and add the required permissions.
**Permission scopes of Outlook Calendar:**
| Scope | Description |
|------------------------------|-----------------------------------------------------------------------------------------------------------------------|
| Calendars.ReadWrite | The app can create, read, update, and delete events in the user's calendars with the user's permission. |
| Calendars.ReadWrite.Shared | The application can perform operations such as creating, reading, updating, and deleting events in all calendars of the organization that the user has access to, including delegate and shared calendars. |
### 1.3 Enable MS Outlook on Yellow.ai
1. Go to cloud.yellow.ai > **Integrations**.
2. Search for **Outlook calendar** and enter the obtained **Tenant ID**, **Client ID** and **Client Secret** from the Azure portal in the integration card and click **Connect**.
You'll need to log in to your Microsoft work account and give the app permission to access your calendar data.
3. If you have multiple accounts, follow the above mentioned steps to add each of them.
:::note
1. Enter a unique name for each account to easily identify them within the yellow.ai platform. It is recommended to use a name that aligns with its purpose for better usability.
2. You can add a maximum of 15 accounts.
3. In a two-tier environment, such as bots with only Development/Live environments, you can add account names only in the development mode. Once added and flows have been built, in the Live mode, you can only choose the account names and not edit them.
4. In a three-tier environment, such as bots with Staging/Sandbox/Production modes, in Staging and Sandbox modes, you can add and edit new accounts. However, in Production, only the account details added in Staging will be available. You can only map in the production environment.
:::
## 2. Use-cases
This integration currently supports the following use-cases:
:::note
When multiple accounts are added, select the appropriate account for each node, allowing you to leverage the unique functionalities of each account for their intended purposes.
:::
### 2.1 Create calendar event
This actions allows you to create online events in your default calendar, specifying the date, time, and time zone. Invitations are automatically sent to attendees' Outlook inboxes. Recurring events can also be set up.
The table below has sample inputs, data types and remarks of the fields for this action.
| Field Name | Sample Input | Datatype | Remarks |
|----------------|----------------------------------------------------------------------------|-------------|---------------------------------------------------------------------------|
| Start time | `{"dateTime":"2023-04-11T09:00:00.000","timeZone":"India Standard Time"}` | Object Type | The start date, time, and time zone of the event. |
| End time | `{"dateTime":"2023-04-11T10:00:00.000","timeZone":"India standard Time"}` | Object Type | The date, time, and time zone when the event concludes. |
| Can invitees propose a new time? | True | bool | The meeting organizer has enabled the option for invitees to suggest an alternative time while responding. |
| Attendee details | `[{"emailAddress":{"address":"samanthab@contoso.onmicrosoft.com","name":"Pradeep"},"type":"required"}]` | Array | The list of people attending the event. |
| Meeting description | `{"contentType":"HTML","content":"Scrum"}` | Object Type | Meeting agenda |
| Importance of the event | High | String | The priority of the event, the possible values are: low, normal, high. |
| Recurrence | `{"pattern":{"type":"daily","interval":3},"range":{"type":"endDate","startDate":"2023-04-11"}}` | Object Type | The pattern of how often the event will occur. |
| Meeting title | Scrum | String | A brief summary that identifies the purpose of the meeting. |
**Sample response:**
```
{
"id":"AAMkAGI1AAAt9AHjAAA=",
"createdDateTime":"2017-04-15T03:00:50.7579581Z",
"onlineMeetingUrl":null,
"isOnlineMeeting":true,
"body":{
"contentType":"html",
"content":"Does late morning work for you?"
},
"start":{
"dateTime":"2017-04-15T11:00:00.0000000",
"timeZone":"Pacific Standard Time"
},
"end":{
"dateTime":"2017-04-15T12:00:00.0000000",
"timeZone":"Pacific Standard Time"
},
"recurrence":null,
"attendees":[
{
"type":"required",
"status":{
"response":"none",
"time":"0001-01-01T00:00:00Z"
},
"emailAddress":{
"name":"Samantha Booth",
"address":"samanthab@contoso.onmicrosoft.com"
}
}
],
"organizer":{
"emailAddress":{
"name":"Dana Swope",
"address":"danas@contoso.onmicrosoft.com"
}
}
},
"onlineMeeting": {
"joinUrl": "https://teams.microsoft.com/l/meetup-join/19%3ameeting_MDJmZWY5NTUtY2YxNy00NTJjLTllMWMtNGUxOGM0MWE5ZTEy%40thread.v2"
}
```
### 2.2 Get calendar events
The Get Calendar Events function returns a list of events from the your default calendar based on the defined start and end date time, including both single instance and recurring meetings.
The table below has sample inputs, data types and remarks of the fields for this action.
| Field Name | Sample Input | Data Type | Remarks |
|--------------------|-----------------------------|-----------|---------------------------------------------------------------------|
| Start date time | 2023-04-11T12:00:00.000 | String | The start date, time, and time zone of the event. |
| End date time | 2023-04-12T12:00:00.000 | String | The date, time, and time zone when the event concludes. |
| Response time zone | India standard time | String | Returns the event’s start time and end time in the specified time zone. |
**Sample Response:**
```
{
"value": [
{
"id": "AWtBH7_RLmY0nAoX3PzBwCh69yUb7hwSIjZoGosUcSzAAAAAAENAACh69yUb7hwSIjZoGosUcSzAAATuTBzAAA=",
"subject": "Hangouts",
"isCancelled": false,
"type": "singleInstance",
"allowNewTimeProposals": true,
"recurrence": null,
"start": {
"dateTime": "2023-04-15T05:30:00.0000000",
"timeZone": "UTC"
},
"end": {
"dateTime": "2023-04-15T06:30:00.0000000",
"timeZone": "UTC"
},
"attendees": [
{
"type": "required",
"status": {
"response": "none",
"time": "0001-01-01T00:00:00Z"
},
"emailAddress": {
"name": "Samantha Gupta",
"address": "samanthab@contoso.onmicrosoft.com"
}
}
],
"onlineMeeting": {
"joinUrl": "https://teams.microsoft.com/l/meetup-join/19%3ameeting_NzI1ZWNkMTQtYjM0OS00MzViLWE5ZmYtMDA2NTA4NGViMDZh%40thread.v2/0?context=%7b%22Tid%22%3a%"
}
}
```
### 2.3 Recommend meeting slots
This option allows you to set parameters such as date, time, and attendees for a meeting. It takes into consideration everyone's schedules and suggests appropriate times for the meeting. If it can't suggest any times, it will let you know why, such as if the organizer or a required attendee is unavailable. You can use this information to adjust your parameters and try again.
The table below has sample inputs, data types and remarks of the fields for this action.
| Field Name | Sample Input | Data Type | Remarks |
|--------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Time constraints | `{"timeslots":[{"end":{"dateTime":"2023-04-11T12:30:20.2020","timeZone":"India Standard Time"},"start":{"dateTime":"2023-04-11T09:00:00.000","timeZone":"India Standard Time"}},null]}` | Object | You can set restrictions on a meeting's timing and nature by specifying the activity domain and available time slots. |
| Attendee details | `[{"emailAddress":{"address":"samanthab@contoso.onmicrosoft.com","name":"Samantha"}}]` | Array | Details of the people who will attend or be involved in the meeting. |
| Length of the meeting in minutes | `60` | String | The length of the meeting |
| Response time zone | `India standard time` | String | This provides the event's start and end times in the designated time zone. |
**Sample Response**
```
{
"@odata.context":"https://graph.microsoft.com/v1.0/$metadata#microsoft.graph.meetingTimeSuggestionsResult",
"emptySuggestionsReason":"",
"meetingTimeSuggestions":[
{
"confidence":100.0,
"organizerAvailability":"free",
"suggestionReason":"Suggested because it is one of the nearest times when all attendees are available.",
"meetingTimeSlot":{
"start":{
"dateTime":"2017-04-21T14:00:00.0000000",
"timeZone":"Pacific Standard Time"
},
"end":{
"dateTime":"2017-04-21T16:00:00.0000000",
"timeZone":"Pacific Standard Time"
}
},
"attendeeAvailability":[
{
"availability":"free",
"attendee":{
"type":"required",
"emailAddress":{
"address":"samanthab@contoso.onmicrosoft.com"
}
}
}
],
}
]
}
```
### 2.4 Update an event
This action allows you to change the details of an event that is already on your calendar. To do this, you need to provide the ID of the event and a new object with the updated information.
The table below has sample inputs, data types and remarks of the fields for this action.
| Field Name | Sample Input | Datatype | Remarks |
|----------------------|--------------------------------------------------------------------------------------------------------------------------|------------|------------------------------------------------------------------------------------------------------------|
| Start time | `{"dateTime":"2023-04-11T09:00:00.000","timeZone":"India Standard Time"} ` | Object Type| Start date, time, and time zone of the event. |
| End time | `{"dateTime":"2023-04-11T10:00:00.000","timeZone":"India standard Time"}` | Object Type| End date, time, and time zone for the event's end. |
| Event ID | AAMkADA1ODMyOWE0LWNkZmUtNDJiYy1hNWI1LWE1NmQwY2RmNDhlOQBGAAAAAAAXtAWtBH7%2BRLmY0nAoX3PzBwCh69yUb7hwSIjZoGosUcSzAAAAAAENAACh69yUb7hwSIjZoGosUcSzAAAFJQ9WAAA%3D | String | Event ID |
| Can invitees propose | True | bool | Option to propose a new time if the organizer allows it. |
| a new time? | | | |
| Attendee details | `[{"emailAddress":{"address":"samanthab@contoso.onmicrosoft.com","name":"Pradeep"},"type":"required"}] ` | Array | List of attendees for the event. |
| Meeting description | `{"contentType":"HTML","content":"Scrum"} ` | Object Type| Message body associated with the event. |
| Importance of event | High | String | Importance of the event (low, normal, or high). |
| Recurrence | `{"pattern":{"type":"daily","interval":3},"range":{"type":"endDate","startDate":"2023-04-11"}}` | Object Type| Recurrence pattern for the event. |
| Meeting title | Scrum | String | A brief summary of the meeting agenda. |
**Sample Response:**
```
{
"originalStartTimeZone": "originalStartTimeZone-value",
"originalEndTimeZone": "originalEndTimeZone-value",
"responseStatus": {
"response": "",
"time": "datetime-value"
},
"recurrence": null,
"reminderMinutesBeforeStart": 99,
"isOnlineMeeting": true,
"onlineMeetingProvider": "teamsForBusiness",
"isReminderOn": true,
"hideAttendees": false,
"onlineMeeting": {
"joinUrl": "https://teams.microsoft.com/l/meetup-join/19%3ameeting_NzIyNzhlMGEtM2YyZC00ZmY0LTlhNzUtZmZjNWFmZGNlNzE2%40thread.v2/0?context=%7b%22Tid%22%3a%2272f988bf-86f1-41af-91ab-2d7cd011db47%22%2c%22Oid%22%3a%22bc55b173-cff6-457d-b7a1-64bda7d7581a%22%7d",
"conferenceId": "177513992",
"tollNumber": "+91 22 6241 6885"
}
}
```
### 2.5 Add an attachment
This action adds a file to an event, and the size of the file should be less than 3 MB.
The table below has sample inputs, data types and remarks of the fields for this action.
| Field Name | Sample Input | Data Type | Remarks |
| --- | --- | --- | --- |
| File URL | https://image.crictracker.com/wp-content/uploads/2019/04/home.jpg | String | URL of the file being attached. |
| Event ID | AAMkAGI1AAAt9AHjAAA= | String | Event ID. |
| Name of the file | image.jpeg | String | Custom name (not necessarily the file name) to be displayed with the attachment icon. |
**Sample Response**
```
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('6aoGosUcSzAAAAAAENAACh69yUb7hwSIjZoGosUcSzAAATuTBwAAA%3D')/attachments/$entity",
"@odata.type": "#microsoft.graph.fileAttachment",
"@odata.mediaContentType": "image/png",
"id": "AAMkADA1ODMyOWE0LWNkZmUtNDJiYy1hNWI1LWE1NmQwY2RmNDhlOQBGAAAAAAAXtAWtBH7_RLmY0nAoX3PzBwCh69yUb7hwSIjZoGosUcSzAAAAAAENAACh69yUb7hwSIjZoGosUcSzAAATuTBwAAABEgAQAKfJP9iJETBGnLIDXGog7_Q=",
"lastModifiedDateTime": "2023-03-30T06:05:51Z",
"name": "mahi.png",
"contentType": "image/png",
"size": 78744,
"contentBytes": "iVBORw0KGgoAAAANSUhEUgAAA7sAAAJKCAYAAADtI1L+AAAAAXNSR0IArs4c6QAAIABJREFUeF7snQf"
}
```
### 2.6 Cancel an event
This action lets the meeting organizer cancel an event by sending a cancellation message, which moves the event to the Deleted Items folder. For recurring meetings, the organizer can also cancel a specific occurrence by providing the occurrence event ID.
The table below has sample inputs, data types and remarks of the fields for this action.
| Field Name | Sample Input | Data type | Remarks |
|-----------------------------|------------------------------|-----------|--------------------------|
| Event ID | AAMkAGI1AAAt9AHjAAA= | String | Event ID. |
| Send a cancellation message | Out of office | String | Sends a cancellation message. |
### 2.7 Get event details
This action will provide information about a specific event, including its properties and relationships. The start and end times of the event will be in the time zone chosen by the user.
The table below has sample inputs, data types and remarks of the fields for this action.
| Field Name | Sample Input | Data type | Remarks |
| ------------------ | --------------------------------------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Event ID | AAMkADA1ODMyOWE0LWNkZmUtNDJiYy1hNWI1LWE1NmQwY2RmNDhlOQBGAAAAAAAXtAWtBH7%2BRLmY0nAoX3PzBwCh69yUb7hwSIjZoGosUcSzAAAAAAENAACh69yUb7hwSIjZoGosUcSzAAAFJQ9WAAA%3D | String | Unique identifier for the event |
| Response time zone | India standard time | String | Provides the start and end time of the event adjusted to the time zone specified by the user. |
### 2.8 Get busy time slots
This action shows a someone's scheduled events during a specific time period from their default calendar, indicating whether they are free or busy. If no events are scheduled, the user is assumed to be free during that time range.
The table below has sample inputs, data types and remarks of the fields for this action.
| Field Name | Sample Input | Datatype | Remarks |
|--------------------|--------------------------------------------------------------------------------------------------|----------|-------------------------------------------------------------------------------------------------|
| Email addresses | `["samanthab@contoso.onmicrosoft.com", "Rahul@contoso.onmicrosoft.com"] ` | Array | SMTP addresses of users to get availability information for. |
| Start time | `{"dateTime":"2023-04-04T09:00:00.000","timeZone":"India Standard Time"}` | Object | The start date, time, and time zone of the event. |
| End time | `{"dateTime":"2023-04-04T12:43:49.4949","timeZone":"India standard Time"}` | Object | The end date, time, and time zone of the event. |
| View available interval | 40 | number | Duration of a time slot in the [availability View] of the response. |
---
## Integration overview
The integration module lets you connect your AI Agent with third-party systems, enabling access to various functionalities within the Yellow.ai platform. These integrations act as bridges between your AI Agent and external platforms, facilitating smooth communication and data exchange. Whether streamlining processes, automating tasks, or enhancing customer experiences, integrations are crucial for maximizing the utility and impact of your AI agent.
To make it easy to access and manage your integration accounts, they are conveniently organized into different categories.
## Integration process
To integrate your application with our platform, follow these step-by-step instructions:
### Step 1: Gather integration details from your integration app
1. **Login to your integration application:** Access your application's dashboard or admin panel.
2. **Retrieve integration details:** Locate and collect all the necessary details required for integration, such as client ID, secret key, and domain URL. Refer to your application's documentation for more specific instructions on where to find these details.
### Step 2: Connect your integration account to yellow.ai platform
You can connect your account only in development environment and not in live. For a three-tier environment, you can connect an account in Staging and Sandbox environment. Once the AI Agent is published, it will use the integrations if they are configured in the flows.
1. **Login to our [Cloud platform](https://cloud.yellow.ai)** with your credentials and switch to Development/Staging environment.
2. Navigate to **Extensions** > **Integration** and search for the integration app.
3. Proceed by entering the integration details collected in Step 1 to establish the connection with your account.
4. Click **Connect**.
5. Similarly, You can add more accounts by clicking the **+Add Account** button. You can connect up to 15 accounts per integration.
### Step 3: Configure Webhook URL
Webhooks function as callback endpoints, sending updates to a specified URL whenever there's a change in the integration app. If you do not configure, the AI Agent won't receive these events, potentially disrupting the integration's operation.
Once the connection is estabblished, follow these steps to configure the webhook URL:
1. Once the connection is established, a unique webhook URL will be generated for your account. Go to the connected app and **Copy Webhook URL**.
2. **Paste the URL** into the relevant settings section of your integration app. This allows your integration app to send data to our platform seamlessly.
### Step 4: Enable integration events in your AI Agent
This enables you to execute specific actions in response to events. For instance, you can display a message in the AI Agent conversation when a payment is successful or show order details when an order is placed.
1. In Development/Staging environment, go to **Automation** > **Event** > **Integrations**.
2. Find the event and click on the three dots icon, then select **Activate**. Events are named with the Integration app name, for instance, "InstaMojo Payment Status".
### Step 5: Trigger AI Agent flows with integration events
You can configure your AI Agent to [trigger specific flows when an event occurs](https://docs.yellow.ai/docs/platform_concepts/studio/build/Flows/configureflow). For instance, display a message when a payment is successful or show order details after an order is placed.
1. At the start of the flow, select *Events* and then choose the specific event that you want to use.
2. If there are multiple accounts connected, you will see the Account Name dropdown where you can choose a specific account that you want to use.
3. Publish your AI Agent for your changes to reflect in the *Live* or *Production* environment.
#### Step 5: Configure AI Agent to handle specific integration actions
Once the integration is enabled, your AI Agent gains the ability to directly perform various actions within that specific integration account. These actions may include creating new records, updating existing records, and retrieving specific information. With this capability, you can configure your bot to handle these specific integration actions seamlessly.
To perform a specifc integration action via AI Agent:
1. In Development/Staging environment, navigate to **Automation** > **Build** > Select the flow where you want to use an integration action.
2. Click **Add node** > **Integrations** > `{Integration Name}`.
3. Once you've added the respective integration node, you'll see a list of supported actions along with their configurations. Select the action you need and configure the necessary fields accordingly.
4. Customize the AI Agent's behavior to respond appropriately to integration events, such as sending notifications or executing automated tasks.
5. Publish your AI Agent for your changes to reflect in the *Live* or *Production* environment.
1. **Define AI Agent Actions:** Once integration events are enabled, configure your bot to perform specific actions in response to these events.
2. **Customize AI Agent Behavior:** Customize the bot's behavior to respond appropriately to integration events, such as sending notifications or executing automated tasks.
By following these steps, you can seamlessly integrate your application with our platform and leverage the full capabilities of our bot system. If you encounter any issues or need further assistance, please refer to our documentation or contact our support team for help.
---
## Integration types
### 1. CRM
CRM consists of integrations with customer relationship management tools used for managing the leads and opportunities. Click on any of the below mentioned integrations with CRMs that you wish to setup in order to understand the features, limitations and setup instructions:
Integration | Description
----------- | -----------
[Hubspot](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/hubspot-crm) | The HubSpot CRM integration allows you to customize lead details through a conversational bot, enhancing lead management processes and providing personalized experiences for your customers.
[Microsoft Dynamics 365](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/microsoft-dynamics) | The Microsoft Dynamics 365 CRM & ERP system integration enables your AI Agentt to create Leads, Opportunities, and perform other operations from your AI Agent.
[Salesforce CRM](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/salesforce-service-cloud) | The Salesforce CRM integration empowers your conversational AI Agent to create Leads, Opportunities, and perform other functions, enhancing efficiency and streamlining processes for your users.
[Zoho-CRM](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/zoho-crm) | The Zoho CRM integration enables your AI Agent to create Leads, Opportunities, and perform other Zoho CRM related operations.
[Epic FHIR](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/epic-fhir) | Integrate Epic FHIR with Yellow.ai and fetch and modify medical records.
---
### 2. ITSM
ITSM consists of integrations with IT service management tools used for managing service delivery. Click on any of the below mentioned integrations with ITSM tools that you wish to setup in order to understand the features, limitations and setup instructions:
Integration | Description
----------- | -----------
[Freshservice ITSM Solution](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/freshservice) | Integrate your Freshservice instance for seamless service delivery processes.
[Service Now](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/service-now) | Integrate with ServiceNow for ticket updates & accessing FAQ repositories for possible responses.
[SAP IO](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/sap-io) | This integration allows you to receive events for SAP objects. Furthermore, this also lets you perform actions, such as create, update, get and delete the tickets.
---
### 3. HR
HR consists of integrations with human resource softwares used for managing recruiting, onboarding and HR related services. Click on any of the below mentioned integrations with HR tools that you wish to setup in order to understand the features, limitations and setup instructions:
Integration | Description
----------- | -----------
1. [Freshteam](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/freshteam) | Freshteam is a smart HR software that helps you handle recruiting, onboarding, time off and employee information in one place.
2. [SAP Success Factors](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/successfactors#references) | With SAP Successfactors integration, you can automate recruitment cycle through conversational bots.
[Bamboo HR](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/bamboohr) | The Bamboo HR integration allows you to seamlessly connect your Bamboo HR service with the yellow.ai platform.
---
### 4. Tools & Utilities
To explore integrations with tools & utilities softwares, click on any of the below mentioned integrations with that you wish to setup in order to understand the features, limitations and setup instructions:
| Integration Name | Description |
|-----------------------|------------------|
| [Azure Active Directory](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/azure-ad#references) | The Azure Active Directory integration supports use-cases related to Azure AD, providing seamless access and management within your bot ecosystem.|
| [Clever Tap](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/clevertap) | The Clever Tap integration allows seamless incorporation of Clever Tap functionalities into your bot, enhancing user engagement and analytics capabilities. |
| [Google Calendar](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/google-calendar) | The Google Calendar integration enables the creation of events within conversational bots, facilitating efficient scheduling and organization. |
| [Google Sheets](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/google-sheets) | The Google Sheets integration enables the creation of new spreadsheets and allows for reading, writing, and updating data in the cells. |
| [JIRA](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/jira) | The JIRA integration enables conversational bots to manage and update dashboards within your JIRA project, facilitating streamlined project management and collaboration.|
| [LeadSquared Whatsapp Connector](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/leadSquared-wa-connector) | The LeadSquared integration empowers conversational bots to efficiently manage and update dashboards within your LeadSquared project, streamlining operations and enhancing productivity. |
| [Microsoft Graph](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/microsoft-graph) | The Microsoft Graph integration enables conversational bots to manage and update dashboards seamlessly, leveraging the capabilities of the Microsoft Graph platform. |
| [Netcore Smartech](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/netcore) | The Netcore Smartech integration enhances customer experience within your conversational bot, providing a seamless platform for engagement and interaction. |
| [SFTP](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/sftp) | The SFTP integration facilitates file transfer and directory reading from remote locations, enhancing data management capabilities within the bot. |
| [Twilio Verify](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/twilio-verify) | The Twilio integration enables conversational bots to trigger verification SMS, seamlessly enhancing security and authentication processes. |
| [WebEngage](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/webengage) |The WebEngage integration allows you to manage your campaigns within conversational bots, streamlining the process and enhancing engagement. |
| [Atlassian](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/atlassian) | The Atlassian integration allows the bot to manage all Atlassian activities from the Yellow.ai platform, granting access to your Atlassian account and enabling them to perform Atlassian actions directly within the Yellow.ai bot. |
| [Freshdesk](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/freshdesk) | Freshdesk integration enables the bot to perform various actions, including creating/updating tickets, fetching ticket details, modifying ticket forms, retrieving agent info, creating notes, and adding watchers to the tickets. |
| [Google Playstore](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/playstore) | The Google Playstore integration allows for active management of user ratings and reviews for your Google Play store account within Yellow.ai. |
| [GPT-3](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/gpt3) | The GPT-3 integration allows for seamless integration of OpenAI's GPT-3, supporting DaVinci, Curie, Babbage, and custom language models within the bot. |
| [LLM](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/llm) | The LLM integration enables to add custom language models to your Yellow.ai account. |
| [Oracle Responsys](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/oracle-responsys) | The Oracle integration enables opportunities to engage with leads and contacts on their preferred messaging platform using Oracle Responsys. |
| [Okta](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/okta) | The Okta integration enables secure authentication and authorization services within your Yellow.ai platform. |
---
### 5. Retail/ ecommerce
Retail/ ecommerce consists of integrations with tools used for managing retail and ecommerce flows. Click on any of the below mentioned integrations that you wish to setup in order to understand the features, limitations and setup instructions:
Integration | Description
----------- | -----------
1. [Shopify Shop](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/shopify) | The Shopify integration allows you to initiate Ecommerce flows seamlessly, enhancing the shopping experience within your bot.
2. [Magento](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/magento) | The Magento integration enables your bot to seamlessly connect with your Magento store. This integration allows your bot to showcase inventory categories, display products, retrieve customer details via email, allow order placement, and enable order status inquiries using the order ID, all within the conversational interface.
---
### 6. Live Chat
Live Chat consists of integrations with tools used for managing agent connectivity and interactions. Click on any of the below mentioned integrations with live chat tools that you wish to setup in order to understand the features, limitations and setup instructions:
Integration | Description
----------- | -----------
[Amazon Connect Live Chat](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/amazon-livechat) | The Amazon Connect integration enables the creation of a conversational bot that seamlessly connects with live agents, enhancing customer support experiences. Additionally, you can develop a custom bot for your team to accelerate teamwork and collaboration processes.
[Avaya Live Chat](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/avaya) | The Avaya integration enables users to connect with live agents for their queries, enhancing customer support capabilities within the bot.
[Custom Live Agent](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/customliveagent) | The Custom Live Agent integration enables the development of a conversational bot that seamlessly connects users to human support, enhancing customer service experiences and ensuring effective communication between users and live agents.
[Freshchat](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/freshchat) | The Freshchat integration allows for the creation of a conversational bot that seamlessly connects with live agents, improving customer support interactions and enabling real-time communication between users and agents.
[Genesys PureCloud Live Agent](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/genesys-cloud-livechat) | The Genesys PureCloud integration enables the development of a conversational bot that seamlessly connects with live agents, enhancing customer support experiences and facilitating effective communication between users and agents.
[Intercom Live Chat](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/intercom-livechat) | The Intercom integration enables seamless live agent transfer, enhancing customer support experiences by facilitating smooth transitions between automated assistance and live agent support within your bot ecosystem.
[Kapture CRM Live Chat](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/kapture-crm) | The Kapture CRM integration within Yellow.ai enhances customer relationship management capabilities, streamlining interactions and processes.
[Locobuzz Live Chat](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/locobuzz-livechat) | The Locobuzz integration enables live agent connections for user queries through the conversational bot, enhancing customer support experiences and facilitating seamless communication between users and agents.
[Salesforce Live Chat](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/salesforce-service-cloud) | The Salesforce Live Chat integration enables the creation of a conversational bot that connects to LiveAgent, enhancing customer support experiences and facilitating seamless communication within your organization.
[Talisma Live Chat](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/talisma) | The Talisma Live Chat integration enables seamless connections with live agents, enhancing customer support experiences and enabling real-time communication within your organization's conversational bot ecosystem.
[Zoho Live Chat](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/zoho-live-chat) | The Zoho Live Chat integration facilitates seamless conversation transfer, enhancing customer support experiences and enabling smooth communication transitions within your organization's conversational bot ecosystem.
[Genesys Live Chat](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/genesys) | The Genesys integration enables seamless connections with live agents, enhancing customer support experiences and facilitating real-time communication within your organization's conversational bot ecosystem.
[Microsoft Dynamics 365](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/microsoft-live) | The Microsoft Dynamics 365 integration enables direct connections with live agents, enhancing customer support experiences and facilitating seamless communication within your organization's conversational bot ecosystem.
[Genesys Purecloud Live](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/genesys-cloud-livechat) | The Genesys PureCloud Live integration allows direct connections with live agents, enhancing customer support experiences and facilitating seamless communication within your organization's conversational bot ecosystem.
[Service Now live](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/servicenow-livechat) | The ServiceNow Live integration enables connecting with live agents on ServiceNow Live directly from your yellow.ai bot, enhancing customer support experiences and facilitating seamless communication within your organization
---
### 7. Payment
Payment consists of integrations with tools used for managing payment and related requests. Click on any of the below mentioned integrations with payment tools that you wish to setup in order to understand the features, limitations and setup instructions:
Integration | Description
----------- | -----------
[Camspay](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/camspay) | Integrate with CAMSPay to fulfil your payment requirements, including creating payment links and monitoring the progress of payments or refunds.
[Cashfree Payments](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/camspay) | With Cashfree Payment Integration, you can generate payment links and check the status of payments made, streamlining transaction processes and enhancing user experiences within your bot ecosystem.
[Paytm](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/paytm) | With Paytm integration, you can create payment links and check the status of payments made, streamlining transaction processes and enhancing user experiences within your bot conversations
[PayU Business](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/payuBiz) | With PayU Business integration, bot can handle secure and seamless payment transactions. This enables users to complete purchases, subscriptions, or bill payments directly within the chat interface.
[Razorpay](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/razorpay) | With Razorpay integration, you can streamline payment processes by creating payment links and checking the status of payments or refunds, enhancing user experiences within your bot conversations.
[Stripe Payment Gateway](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/stripe) | With Stripe integration, you can meet your payment needs, such as generating payment links and checking the status of payments and refunds, streamlining transaction processes and enhancing user experiences within your AI Agent.
[Airpay](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/airpay) | With Airpay integration, Yellow.ai enables users to make payments directly through the chat interface, facilitating seamless transactions and enhancing user experiences within your ecosystem.
[BillDesk Email pay](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/billdesk-emailpay) | With BillDesk EmailPay integration, you can seamlessly receive payments from your users, enhancing transaction processes and user experiences within your Yellow.ai account.
[Billdesk UPI](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/billdesk) | With BillDesk UPI, you can seamlessly create UPI intents for WhatsApp Pay, view payment statuses, and send UPI notifications directly within the Yellow.ai platform.
[Stripe](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/stripe) | With Stripe Payment integration, you can generate payment links and view payment statuses directly within the Yellow.ai platform.
---
## Paytm Payment Gateway
Yellow.ai Integration with Paytm Payment Gateway enables the end user to do the following:
1. Generate a payment link and receive an intimation regarding the status of the payment as to whether it was a success or failure.
2. Initiate the process of refund.
3. Check the status of the refund that was initiated.
## Connect Paytm payment gateway with Yellow.ai
In a two-tier environment, you can connect an integration app in the Development environment. In a three-tier environment, you can connect the integration app either in Staging or Sandbox. All connected integrations are available in the live environment.
To integrate the Paytm payment gateway, follow these steps:
1. Navigate to the Development/Staging environment and go to **Extensions** > **Integrations** > **Payment** > **Paytm**. You can also search the integration by name **Paytm** using the Search box.
2. In **Give account name**, enter a unique name for the integration. You can use only lowercase alphanumeric characters and underscores (_).
3. In **Merchant ID**, enter the Merchant ID provided by the client or Paytm SPOC.
4. In **Merchant Key** enter the Merchant Key provided by the client or Paytm SPOC.
5. In **API Domain**, If you intend to use the staging domain of Paytm, enter `https://securegw-stage.paytm.in`. If you're using the production domain, enter `https://securegw.paytm.in`.
6. In **Channel ID**, enter the Channel ID provided by the client or Paytm SPOC.
7. **Industry Type:** Enter the Industry Type provided by the client or Paytm SPOC.
8. To add more accounts, click **+ Add account** and proceed with the previous steps. You can add a maximum of 15 accounts.
## Configure Webhook URL in Paytm
The webhook URL serves as a callback endpoint where Paytm can send notifications or updates regarding payment events, enabling your application to respond accordingly.
1. Go to the connected Paytm integration and copy the webhook URL.
2. Add domain URL. Append the region of your AI agent to the domain of the webhook url. r1/r2/r3/r4/r5 are the regions of your AI agent, you can refer the following list for the same. (r1 = MEA, r2 = Jakarta, r3 = Singapore, r4= USA, r5 = Europe)
3. Login to your Paytm account and navigate to the Webhook URL Configuration section and add the provided webhook URL.
## Enable Paytm event for your AI agent
1. On the Cloud Platform go to Staging/Development environment.
2. On the left navigation bar, click **Automation** > **Event** > **Integrations** and search for `Paytm Payment Status`.
3. Click on the more options icon and select Activate. If you have connected multiple accounts, you need to enable the event for each account.
4. Once the event is activated, you can create a flow in the **Automation** > **Build** and use the event in a flow to trigger a specific action, such as displaying a message indicating that the payment is completed successfully.
**Sample webhook event data sent by Paytm**
```
{
"PAYMENTEMAILID": "user@example.com",
"PAYMENTMOBILENUMBER": "7777777777",
"GATEWAYNAME": "WALLET",
"RESPMSG": "Txn Success",
"BANKNAME": "WALLET",
"PAYMENTMODE": "PPI",
"CUSTID": "CUST_001",
"MID": "INTEGR7769XXXXXX9383",
"MERC_UNQ_REF": "LI_12345",
"RESPCODE": "01",
"TXNID": "202005081112128XXXXXX68470101509706",
"TXNAMOUNT": "1.00",
"ORDERID": "ORDERID_98765",
"STATUS": "TXN_SUCCESS",
"BANKTXNID": "63240520",
"TXNDATETIME": "2020-09-10 13:03:05.0",
"TXNDATE": "2020-09-10",
"CHECKSUMHASH": "PMXJocjUUKGq7MXGwHO0LNOV+YxwuYi4gKjRgFOIZVGVqyxqfFuec+A8boUq5Q3c87yYM9DOeCmjIj5mH20SfIiDjOJiU4eFzNxu0J1qKdc=",
"LINKNOTES": "Link Note Description"
}
```
## Paytm actions through AI agent conversation
Once your Paytm account is successfully connected, your AI agent can perform the following actions:
:::note
If there are multiple accounts, you can select from which account you want to perform the action.
:::
### Generate Paytm payment link in AI agent conversation
1. Go to Development/Staging environment and navigate to **Automation** > **Build** > Select the flow where you want to add the Generate payment link node.
2. Click **Add node** > **Integrations** > **Paytm**.
3. You will see the Paytm node. In the first drop-down (actions), choose *Generate Payment Link*.
3. Configure the input parameters needed to generate the payment link by referring to the descriptions provided in the table below.
| Field name | Sample value | Data type | Description |
| -------- | -------- | --- | -------- |
| Timestamp | 1588402269 | String | EPOCH timestamp of the time at which the request is being sent |
|Amount|3500|String|Transaction amount|
|LinkName|Test|String|Name of the link that you want to display to the customer, link name is used to generate a long URL|
|LinkType|FIXED|String|Type of link|
|LinkDescription|Test|String|Description of the link that you want to display to the customer|
|SendSms|true/false|Boolean|Flag whether SMS is to be sent to the customer by Paytm|
|SendEmail|true/false|Boolean|Flag whether Email is to be sent to the customer by Paytm|
|CustomerName|Mahesh|String|Name of the customer|
|CustomerEmail|test@gmail.com|String|Email ID of the customer|
|CustomerMobile|9870000000|String|Mobile number of the customer|
|LinkNotes|Reference details|String|Add additional notes to your link. This won’t be shown to the customers|
:::note
An easy way to determine the success or failure of an action is by inspecting the key tokenType in the head object. If its value is **AES**, the response indicates success.
:::
**Sample response for success**
In case of success, you must extract the key **shortUrl** present in the **body** object and display it to the end user with an appropriate message with the help of any of the **Message type** nodes.
```
{
"head": {
"version": null,
"timestamp": "1566994462639",
"channelId": null,
"tokenType": "AES",
"clientId": null
},
"body": {
"linkId": 5861,
"linkType": "GENERIC",
"longUrl": "https://securegw-stage.paytm.in/link/PAYMENTLINKNAME/LL_5861",
"shortUrl": "https://paytm.me/ID-PBo7",
"expiryDate": "27/08/2020 17:44:22",
"isActive": true,
"merchantHtml": "",
"createdDate": "28/08/2019 17:44:22",
"notificationDetails": [],
"resultInfo": {
"resultStatus": "SUCCESS",
"resultCode": "200",
"resultMessage": "Payment link is created successfully"
}
}
}
```
**Sample response for fallback**
```
{
"head": {
"version": "v2",
"timestamp": "28/08/2019 17:47:22",
"channelId": null,
"tokenType": null,
"clientId": null
},
"body": {
"resultInfo": {
"resultStatus": "FAILED",
"resultCode": "302",
"resultMessage": "link name contains sepcial character."
}
}
}
```
**To use this Integration Action Node in an app.yellow.ai AI agent**, refer to the below-mentioned example:
```
app.executeIntegrationAction({
"integrationName": "paytm",
"action": "Generate Payment Link",
"dynamicParams": {
"amount": "5",
"timestamp": "1658203708983",
"linkName": "Test",
"linkType": "FIXED",
"linkDescription": "Test Description",
"sendSms": false,
"sendEmail": false,
"customerName": "John Doe",
"customerEmail":"test@test.com",
"customerMobile":"9955995500",
"linkNotes":"test note"
}
}).then((res)=>{
console.log("response from action node", res);
app.log(res, '||Response from action node||')
}).catch((err)=>{
console.log("Error in action node",err);
app.log(err, '||Error in action node||')
})
```
### Initiate Paytm Refund
1. In the Paytm node, choose the action *Initiate refund*.
2. Configure the input parameters needed to generate the payment link by referring to the descriptions provided in the table below.
| Field name | Data type | Description | Sample value |
| -------- | -------- | --- | -------- |
|RequestTimestamp|String|POCH timestamp of the time at which the request is being sent|1588402269|
|OrderId|String|It is a unique reference ID for a transaction passed in the transaction request. Order ID should be passed to raise the refund|OREDRID_98765|
|ReferenceId|String|Unique Reference ID for refund transaction which is generated by merchant. Duplicate REFID will be rejected by the Paytm gateway|REFUNDID_98765|
|TransactionId|String|TXNID is the Paytm payment Transaction ID against which the refund transaction is being placed.TXNID is provided in response payload for every payment transaction| 202005081112128XXXXXX68470101509706|
|RefundAmount|String|Amount for which the refund is to be made. It can be equal to or less than the transaction amount and should be up to two decimal places. The only special character allowed is (".")|30.00|
**Sample response for success**
In case of success, you need to extract the key **resultStatus**, and **resultMsg** in the **resultInfo** object and display them to the end user with an appropriate message with the help of any of the **Message type** nodes.
```json
{
"head": {
"responseTimestamp": "1567421120859",
"signature": "WaFdplm36GmfBtZ6jPIFClLSEffhAk9fTpJ6i8WpgqiZvtUNl53mLL7mu4JWwxPpfSa5pdexyxK/68WtoTmd53TI+R9GffjGc3USoLgWcKI=",
"version": "v1"
},
"body": {
"txnTimestamp": "2019-09-02 12:31:49.0",
"orderId": "YOUR_ORDER_ID",
"mid": "YOUR_MID_HERE",
"refId": "UNIQUE_REFUND_ID",
"resultInfo": {
"resultStatus": "PENDING",
"resultCode": "601",
"resultMsg": "Refund request was raised for this transaction. But it is pending state"
},
"refundId": "PAYTM_REFUND_ID",
"txnId": "PAYTM_TRANSACTION_ID",
"refundAmount": "1.00"
}
}
```
**Sample response for fallback**
```json
{
"head": {
"responseTimestamp": "1567421388384",
"signature": "ry2bNQ+iq+geNezbFNBfIkXXWTFPUnavG6XkxciEJUNLmL7Op9S7qWP8V1TGHNYvggw2IsIt1OmprSfq92pODO5xiNJ+6pFyVtBUxnRrdL8=",
"version": "v1"
},
"body": {
"orderId": "YOUR_ORDER_ID",
"mid": "YOUR_MID_HERE",
"resultInfo": {
"resultStatus": "TXN_FAILURE",
"resultCode": "607",
"resultMsg": "Refund can not be initiated for acanceledd transaction."
},
"txnId": "PAYTM_TRANSACTION_ID",
"refundAmount": "1.00"
}
}
```
**To use this Integration Action Node in an app.yellow.ai AI agent**, refer to the below-mentioned example:
```js
app.executeIntegrationAction({
"integrationName": "paytm",
"action": "Initiate Refund",
"dynamicParams": {
"requestTimestamp": "1658203708983",
"orderId": "OREDRID_98765",
"referenceId": "REFUNDID_98765",
"transactionId": "202005081112128XXXXXX68470101509706",
"refundAmount": "30.00"
}
}).then((res)=>{
console.log("response from action node", res);
app.log(res, '||Response from action node||')
}).catch((err)=>{
console.log("Error in action node",err);
app.log(err, '||Error in action node||')
})
```
### Check Refund Status
1. In the Paytm node, choose the action *Check Refund Status*.
2. Configure the input parameters needed to generate the payment link by referring to the descriptions provided in the table below.
| Field name | Sample value | Data type | Description |
| -------- | -------- | --- | -------- |
|RequestTimestamp|1588402269|String|EPOCH timestamp of the time at which the request is being sent|
|OrderId|OREDRID_98765|String|It is a unique reference ID for a transaction passed in the transaction request and the Initiate Refund Integration Action Node. Order ID should be passed to check the actual status of the refund|
|ReferenceId|REFUNDID_98765|String|Merchant's Reference ID unique for every refund transaction. This is REFID for which refund status is being inquired|
:::note
The easiest way to identify success/failure is by looking at the key resultStatus in the resultInfo object. If its value is TXN_SUCCESS, the response is a success.
:::
**Sample response for success**
In case of success, extract the key(s) and display to the end user an appropriate message with the help of any of the Message type nodes.
```json
{
"head": {
"clientId": "C11",
"responseTimestamp": "1556719120393",
"signature": "Stx6P9HpnEG3GADkMuOcj50dm7ZHmvMPd29b8K5rxi4aVzRcJ5hklZo//RZdtTA+zcll8sdelyAYsxqPxFs66RVE0F2b9RElTMqYSfBj89I=",
"version": "v1"
},
"body": {
"orderId": "YOUR_ORDER_ID",
"userCreditInitiateStatus": "SUCCESS",
"mid": "YOUR_MID_HERE",
"merchantRefundRequestTimestamp": "2019-05-01 19:27:25.0",
"resultInfo": {
"resultStatus": "TXN_SUCCESS",
"resultCode": "10",
"resultMsg": "Refund Successfull"
},
"txnTimestamp": "2019-05-01 19:25:41.0",
"acceptRefundTimestamp": "2019-05-01 19:27:25.0",
"acceptRefundStatus": "SUCCESS",
"refundDetailInfoList": [{
"refundType": "TO_SOURCE",
"payMethod": "BALANCE",
"userCreditExpectedDate": "2019-05-02",
"userMobileNo": "91-******7777",
"refundAmount": "1.00"
}],
"userCreditInitiateTimestamp": "2019-05-01 19:27:26.0",
"totalRefundAmount": "1.00",
"refId": "UNIQUE_REFUND_ID",
"txnAmount": "10.00",
"refundId": "PAYTM_REFUND_ID",
"txnId": "PAYTM_TRANSACTION_ID",
"refundAmount": "1.00",
"refundReason": "Testing refund reason",
"agentInfo": {
"name": "Lalit",
"employeeId": "Em1-00`",
"phoneNo": "7777777777",
"email": "customer@example.com"
}
}
}
```
**Sample response for fallback**
```json
{
"head": {
"clientId": "C11",
"responseTimestamp": "1556719175104",
"signature": "gJD0EM+p9rGekkXKRt1M0aTUTaqZ6SVcmWfysIO9s9tJKhjrfpySlCEG8Tb97G1h4iYyJuhCglTr1obhO7xX+TIFwlaIgrundaj7dyt2SdA=",
"version": "v1"
},
"body": {
"orderId": "YOUR_ORDER_ID",
"mid": "YOUR_MID_HERE",
"refId": "UNIQUE_REFUND_ID",
"resultInfo": {
"resultStatus": "PENDING",
"resultCode": "501",
"resultMsg": "System Error."
}
}
}
```
**To use this Integration Action Node in an app.yellow.ai AI agent**, refer to the below-mentioned example:
```js
app.executeIntegrationAction({
"integrationName": "paytm",
"action": "Check Refund Status",
"dynamicParams": {
"requestTimestamp": "1658203708983",
"orderId": "OREDRID_98765",
"referenceId": "REFUNDID_98765"
}
}).then((res)=>{
console.log("response from action node", res);
app.log(res, '||Response from action node||')
}).catch((err)=>{
console.log("Error in action node",err);
app.log(err, '||Error in action node||')
})
```
---
## PayU Business
[PayU Business integration](https://payu.in/about-us?_ga=2.219146714.274874686.1677657469-282964387.1677657469) enables your AI agent to receive PayU payments from your users. You can generate payment links, UPI intents for whatsapp pay and receive notifications on the success/failure of the payments.
## Integrating PayU with Yellow.ai
To connect your PayU account with yellow.ai, follow these steps:
### 1.1 Get keys required for your PayU account integration
1. Login to [PayU Dashboard](https://onboarding.payu.in/app/account)
2. Switch to **Live Mode** from the toggle option on the menu bar.
3. Select **Developer** from the menu on the left-pane and select the **API Details** tab if required. Here
- **Key**: The API key required for all payment requests.
- **Salt (32-bit)**: A 32-character string (v1) used to generate a hash. Any one hash codes is required along with the other parameters when submitting a payment request to PayU.
- **Salt (256-bit)**: A more secure, 256-bit string (v2) used for hash generation. Any one hash codes is required along with the other parameters when submitting a payment request to PayU.
:::note
- Alternatively, you can write to [PayUBiz team](mailto:integration@payu.in) for the API keys. They will provide the keys for both the modes.
- For comprehensive guide to [PayU Dashboard, see here](https://docs.payu.in/docs/generate-merchant-key-and-salt-on-payu-dashboard)
:::
### 1.2 Connect PayU Business to yellow.ai
In a two-tier environment, you can connect an integration app in the Development environment. In a three-tier environment, you can connect the integration app either in Staging or Sandbox. All connected integrations are available in the live environment.
1. Navigate to the Development/Staging environment and go to **Extensions** > **Integrations** > **Payment** > **PayU Business**.
2. In **Give account name**, enter a unique name for the integration. You can use only lowercase alphanumeric characters and underscores (_).
3. In **Salt value**, enter the unique hash for each transaction, which is then used to verify the authenticity of the transaction. The Salt Value is provided by PayU and should be kept confidential.
4. Enter the **Client ID**, enter your PayU account's client ID.
5. In **Payu base URL**, enter the base URL to send API requests to the PayU payment gateway for payment processing.
6. In **Payu UPI base URL**, enter the base URL of the PayU UPI to send API requests to the PayU UPI payment gateway for UPI payment processing.
:::note
Payu base URL and and Payu UPI base URL will differ for test and live modes.
Example:
* Test mode - https://test.payu.in
* Live mode - https://info.payu.in
:::
7. Click **Connect** when you're done.
8. To add another account, click **+ Add account** and proceed with the previous steps. You can add a maximum of 15 accounts.
### 1.3 Configure webhook URL
To receive real-time notifications about payment status updates, you need to set up a webhook URL
Copy the webhook URL and the API key mentioned in the **Instructions** section of the PayUBiz Integration section in the yellow.ai platform.
Use the webhook URL specific to your region - [India](https://cloud.yellow.ai/integrations/genericIntegration/payu-payment-gateway/x1668670622130?id=VVKB60XTmBsVV3sALdpMw0Z3rzXHJ2MTA5cOtiHEzRs%3D), [MEA](https://r1.cloud.yellow.ai/integrations/genericIntegration/payu-payment-gateway/x1668670622130?id=VVKB60XTmBsVV3sALdpMw0Z3rzXHJ2MTA5cOtiHEzRs%3D), [Jakarta](https://r2.cloud.yellow.ai/integrations/genericIntegration/payu-payment-gateway/x1668670622130?id=VVKB60XTmBsVV3sALdpMw0Z3rzXHJ2MTA5cOtiHEzRs%3D), [Singapore](https://r3.cloud.yellow.ai/integrations/genericIntegration/payu-payment-gateway/x1668670622130?id=VVKB60XTmBsVV3sALdpMw0Z3rzXHJ2MTA5cOtiHEzRs%3D),[ USA](https://r4.cloud.yellow.ai/integrations/genericIntegration/payu-payment-gateway/x1668670622130?id=VVKB60XTmBsVV3sALdpMw0Z3rzXHJ2MTA5cOtiHEzRs%3D), and [Europe](https://r5.cloud.yellow.ai/integrations/genericIntegration/payu-payment-gateway/x1668670622130?id=VVKB60XTmBsVV3sALdpMw0Z3rzXHJ2MTA5cOtiHEzRs%3D).
To ensure secure communication and enable PayU Business to send payment status updates, you must get the webhook URL whitelisted. Contact the [PayU Integration team](mailto:integration@payu.in) for assistance.
PayUBiz will whitelist the webhook URL provided by the merchant in their systems. You also need to get the webhook URL whitelisted from the can write to the [PayU Integration team](mailto:integration@payu.in) for more information.
### 1.4 Enable PayU event to receive event in AI agent
1. On the [Cloud Platform](https://cloud.yellow.ai) go to Staging/Development environment.
2. On the left navigation bar, click **Automation** > **Build** > **Event** > **Integrations** and search for `PayU Payment Status`.
3. Click on the more options icon and select **Activate**. If you have connected multiple accounts, you need to enable the event for each account.
4. Once the event is activated, you can create a flow in the **Automation** > **Build** and use the event at the start of the flow to trigger a specific action, such as displaying a message indicating that the payment is completed.
## Manage PayU payments from AI Agent conversations
:::note
If there are multiple accounts, you can select from which account you want to perform the action.
:::
### 2.1 Generate payment link
1. When building [Conversation flows](https://docs.yellow.ai/docs/platform_concepts/studio/build/Flows/journeys), add an **Integration action node** and select **PayU Business** from the list of enabled integrations.
2. When you click the node, you will see a drop-down with supported actions in this integration. Select **Generate Payment Link**.
3. Fill in the fields based on the details provided in the following table.
| Field name |Sample value | Data type|Description|
| -------- | -------- | -------- |-------|
| Amount | 100 | String | Amount to be paid using the payment link. |
|ProductInfo|Iphone|String|Name of the product the user wants to purchase.|
|Description|Test|String|Description of the product.|
|CustomerName|Manish|String|Name of the customer.|
|CustomerEmail|test@test.com|String|Email address of the customer.|
|CustomerMobileNumber|9999933344|String|Contact number of the customer.|
|txnID|Order123|String|The unique transaction ID that is generated dynamically.|
|CustomerAddress|Ashoka Road, Mysore, Karnataka|String|Address of the customer.|
|CustomerCity|New york|String|City of the customer.|
|CustomerResidentState|Karnataka|String|State of the customer.|
|CustomerZipcode|845309|String|Pincode of the customer.|
|Send Email|false|Boolean|The email address of the customer to send the invoice.|
|Time Unit|h|String|Frequency(in days, hours, minutes) at which a recurring payment will be charged.|
|UDF|Shipping Method| String| User defined field - used to store any information corresponding to a particular transaction. |
|Validation Period|1|Number|Determines how long PayU will continue trying to charge the customer if the initial payment fails.|
To use this Integration Action Node in an app.yellow.ai AI agent, refer the following example:
```js
app.executeIntegrationAction({
"integrationName": "payu-payment-gateway",
"action": "Generate Payment Link",
"dynamicParams": {
"amount": "1",
"productInfo": "testProduct",
"customerFirstName": "Test Customer",
"customerEmail": "test@test.com",
"customerMobileNumber": "9999999999",
"txnid": "123456789"
}
}).then((res)=>{
console.log("response from action node", res);
app.log(res, '||Response from action node||')
}).catch((err)=>{
console.log("Error in action node",err);
app.log(err, '||Error in action node||')
})
```
### 2.2 Generate UPI intent
1. From the PayU Business node, select *Create UPI intent*.
2. Provide the necessary inputs by selecting the relevant variable for each parameter. Below is a table containing sample values, data types, and descriptions for each of these fields.
| Field name |Sample value | Data type|Description|
| -------- | -------- | -------- |-------|
| Amount | 100 | String | Amount to be paid using the payment link. |
|CustomerEmail|test@test.com|String|Email address of the customer.|
|CustomerPhoneNumber|9999933344|String|Contact number of the customer.|
|CustomerName|Manish|String|Name of the customer.|
Fail URL|https://alpha6.yellowmessenger.com/ |String|The redirection URL in case there's a payment failure.|
|Success URL|https://alpha6.yellowmessenger.com/ |String
The redirection URL in case of successful payment.|
|TXN S2S flow|4|number|Txn S2S flow.|
|Transaction ID|Order123|String|The unique transaction ID that is generated dynamically.|
|Product Info|Iphone|String|Description of the product.|
|UDF| CustomField|String|User defined Field - used to store any information corresponding to a particular transaction. |
3. The **Generate UPI intenrt Integration Action Node** has two outcomes, **success** or **failure**. If the payment link is generated successfully, the **Integration Action Node** returns a **Success** response code as shown below:
```json
{
"metaData": {
"message": null,
"referenceId": "af65159e8566652849bc12a3450a8fca",
"statusCode": null,
"txnId": "wa5iy6b82pvquxcd1vby",
"txnStatus": "pending",
"unmappedStatus": "pending"
},
"result": {
"paymentId": 15961819086,
"merchantName": "wwwmerchantnamecom",
"merchantVpa": "payumoney@hdfcbank",
"amount": "1.00",
"intentURIData": "pa=payumoney@hdfcbank&pn=Gaurav Dua&tr=15961819086&tid=wa5iy6b82pvquxcd1vby&am=1.00&cu=INR&tn=UPI Transaction for wa5iy6b82pvquxcd1vby",
"acsTemplate": "PGh0bWw+PGJvZHk+PGZvcm0gbmFt"
}
}
```
If generating UPI intent fails, the **Integration Action Node** returns a Failure response code as shown below:
```json
{
"message": "[INTG ERROR] Node API Execution failed for payu-payment-gateway_Create UPI Intent in bot x1645073590274: 4xx or 5xx series code encountered",
"name": "IntegrationNodeAPIError",
"apiResponseBody": {
"result": null,
"status": "failed",
"error": "EX117",
"message": "Invalid amount #~#Please ensure that you send all mandatory parameters in the transaction request to PayU.Mandatory parameters which must be sent in the transaction are: key, txnid, amount, productinfo, firstname, email, phone, surl, furl, hash.The parameters which you have actually sent in the transaction are: key, txnid, amount, productinfo, surl, hash, firstname, email, phone.Mandatory parameter missing from your transaction request are: .Please re-initiate the transaction with all the mandatory parameters. "
},
"apiResponseStatusCode": 500
}
```
To use this **Integration Action Node** in an app.yellow.ai AI agent, refer the following example:
```js
app.executeIntegrationAction({
"integrationName": "payu-payment-gateway",
"action": "Create UPI Intent",
"dynamicParams": {
"amount": "1",
"customerName": "farhan",
"customerEmail": "farhan.jafri2011a@gmail.com",
"customerMobileNumber": "9643999539",
"productInfo": "test",
"txnid":"wa5iy6b82pvquxcd1vby",
"successUrl":"https://staging.yellow.ai",
"failUrl":"https://staging.yellow.ai",
"txnFlow": 4
}
}).then((res)=>{
console.log("response from action node", res);
app.log(res, '||Response from action node||')
}).catch((err)=>{
console.log("Error in action node",err);
app.log(err, '||Error in action node||')
})
```
### 2.3 Generate WhatsApp pay
PayU business integration allows your AI agent to accept payments from users via WhatsApp Pay
To configure WhatsApp Pay in the PayU business node, follow these steps:
1. From the PayU business node, select WhatsApp pay.
2. Provide the necessary inputs by selecting the relevant input for each parameter. Below is a table with sample values, data types, and descriptions for each field:
Field name | Sample value | Data type | Description
-----------|-----------|---------|------------
Customer email | rio@gmail.com | String | Email address of the customer. |
Cutsomer name | Rio | String | Name of the customer. |
Fail URL | `https://example.com/payment-failed` | String | URL to redirect to if payment fails.. |
From | +91 98800XXXXX | String | Enter the WhatsApp number that is connected to the AI agent. |
Card description | Mobile charger | String | Deatil of the product |
Order details | `{ "subTotal": 10, "tax": "...", "items": [...] }` | Object | Contains complete order details. |Product info | Wireless charger | String | Information about the product.
Success URL | `https://example.com/payment-success` | String | URL to redirect after a successful payment.
Total amount | 1000 | Number | Total payment amount
Transaction ID | TXN987654321 | String | Unique identifier for the transaction.
Type of Product | Digital goodsPhysical goods | String | Specifies whether the product is digital or physical. |
Image URL | `https://example.com/product-image.jpg` | String | URL of the product image.
UDF1(User defined fileds), UDF2, ......, UDF5 | Custom metadata | String | User-defined fields for passing metadata.
Vpa name | rio@upi | String | Virtual Payment Address (VPA) name.
Preview the WhatsApp AI agent to verify the WhatsApp payment link:
---
## Google Play store Integration
The Google Play Store integration with Yellow.ai enables businesses to monitor and manage app reviews **directly within the AI Agent**, eliminating the need to switch between platforms.
By centralizing review management within the bot, businesses can streamline feedback handling, enhance customer engagement, and reduce response time, all without leaving the Yellow.ai platform.
With this integration, the AI Agent can:
- **Fetch user reviews and ratings**: Automatically retrieve new app reviews and ratings in real time from Google Play Store. This allows teams to track app performance, analyze user sentiment, and respond proactively.
- **Respond to user reviews**: The AI or Human agent can respond to reviews **from within the platform**. The AI Agent can send automated replies, while low ratings can be escalated to a human agent for personalized engagement.
**Limitation**
* Bot or agent can send only one reply per feedback, with a maximum of 250 characters.
**Prerequisites**
Before proceeding with this integration, ensure you have:
* Google play console access
* Google cloud console access
* An Android app deployed on the Play store
## Integrate Google Play store with Yellow.ai
To integrate Google Play store with Yellow.ai, follow these steps:
### Get Google console credentials
For steps to fetch the private key from your google console, click [here](https://www.iwantanelephant.com/blog/2020/11/17/how-to-configure-api-access-to-google-play-console/).
1. Log in to the [Google developer console](https://console.cloud.google.com/).
2. On the [Google console developer](https://developers.google.com/workspace/guides/create-project#create_a_new_google_cloud_platform_gcp_project) portal, click **Go to create a project**.
3. Enter the **Project name**, **Organization**, and **Location**, then click **Create** to create a project.
* Your project will be successfully created.
4. On the navigation panel, go to **IAM & Admin** > **Service Accounts**.
5. Click on **+ CREATE SERVICE ACCOUNT**.
6. Add the *Service Account Details* such as **Service account name**, **Service account ID**, and **Service account description**, then **CREATE AND CONTINUE** in Step 1. Skip Step 2 and 3.
* The service account details for your project will be added successfully.
7. Once the service account is created, click on the **email link**.
8. Go to **KEYS** tab and click on **ADD KEY** > **Create new key**.
9. Select the *Key type* as **JSON** and click **Create**.
:::note
* Ensure that you save this file properly, it cannot be recovered once lost.
:::
• A confirmation message Private key saved to your computer is displayed.
10. Copy the **Private key**, which is required to connect the Google play store with Yellow.ai. For more information, click [here](https://www.iwantanelephant.com/blog/2020/11/17/how-to-configure-api-access-to-google-play-console/).
5. Click **Connect**.
### Connect Google play store to Yellow.ai
To integrate Google play store with Yellow.ai, follow these steps:
1. Login to the [Yellow platform](https://cloud.yellow.ai/) and navigate to the **Development** environment.
* In a two-tier environment, you can only add accounts in the Development environment.
* In a three-tier environment, you can only add accounts in Staging/Sandbox environment.
2. Go to **Extensions** > **Integrations** > **Tools & Utilities** > **Google playstore**. You can also search for Google Playstore in the Search box.
2. In the **Give account name** field, enter a unique name, you cannot edit the account name once it is created.
3. In **Email**, enter the email address of your Google play store account.
4. In **Private key** and **Package name**, enter the private key copied from the Google console and package name of your Google play store account.
5. Click **Connect**.
* Similarly, you can add a maximum of 15 accounts.
## Enable Google play store event to receive events in bot
To receive notifications when a user posts a review for your app on the Google play store, you need to enable the `playstore_review` event in your bot. Once enabled, the bot can automatically fetch new reviews and trigger actions such as responding to feedback or escalating low-rated reviews to a live agent.
To enable Google play store event, follow these steps:
1. On the [Cloud platform](https://cloud.yellow.ai/), go to **Staging** or **Development** environment.
2. On the left navigation bar, click **Automation** > **Event** > **Integrations** and search for `playstore_review`.
3. Click on the **more options** icon and select **Activate**. If you have connected multiple accounts, you need to enable the event for each account.
4. Once the event is activated, navigate to **Automation > Build** to create a flow.
5. Create a new flow and set **playstore_review** as the trigger event and configure action for receiving rating and review.
## Use cases supported for Google play store integration
1. **Fetch user reviews and ratings**: The bot can automatically fetch new app reviews and ratings from the Google play store. This integration enables real-time retrieval of user feedback. This helps to analyse the user sentiment and track app performance.
2. **Send response to user reviews**: The bot or a live agent can respond to user reviews directly from the platform. When a user submits a review, the bot can send an automated response, or if the rating is low, escalate it to a human agent for personalized engagement. However, each review can receive only one response, with a maximum length of 250 characters.
Refer to the following video to see how the Google play store integration works:
---
## Razorpay integration
You can integrate your Yellow.ai platform with your Razorpay account, enabling you to accept payments from your end users. Additionally, this integration allows you to perform various other actions, including:
* Generate a payment link and receive the status (success/failure) of the payment.
* Generate a payment link to receive partial payments and receive the status (success/failure) of the payments.
* Initiate refund process.
* Check refund status.
## 1. Connect Razorpay with Yellow.ai
Connect your Yellow.ai platform with your Razorpay account by following the below-mentioned steps.
### 1.1 Generate API keys on Razorpay dashboard
1. Log into your [Razorpay account](https://dashboard.razorpay.com/signin?screen=sign_in&utm_medium=website&utm_source=direct) and select the mode (Test/Live) for which you want to generate the API key.
* **Test Mode**: The test mode is a simulation mode in which you can test your integration flow. Your customers cannot make payments in this mode. Check out this [video](https://www.youtube.com/watch?v=Xwiv6zSVVCM) to know more.
* **Live Mode**: When your integration is complete, switch to **Live** mode and generate live mode API keys. Replace test mode keys with live mode keys in the integration to accept payments from customers.Check out this [video](https://www.youtube.com/watch?v=30REpNtYSak) to know more.
2. To generate API keys for a specific mode**, navigate to **Settings** > **API Keys** > **Generate Key** to generate key for the selected mode.
3. The **Key Id** and **Key Secret** will appear on the following page. Downalod them to use in your Yellow.ai platform.
### 1.2 Integrate Razorpay with yellow.ai platform
In a two-tier environment, you can connect an integration app in the Development environment. In a three-tier environment, you can connect the integration app either in Staging or Sandbox. All connected integrations are available in the live environment.
To connect your Stripe account with Yellow.ai, follow these steps:
1. Navigate to the Development/Staging environment and go to **Extensions** > **Integrations** > **Payment** > **Razorpay**. You can also search for **Razorpay** in the search box.
2. In **Give account name**, enter a unique name for the integration. You can use only lowercase alphanumeric characters and underscores (_).
3. In **Key ID** and **Key secret**, enter the respective values that you downloaded using the steps mentioned in the previous section.
4. CLick **Connect**.
5. To add another account, click **+ Add account** and proceed with the previous steps. You can add a maximum of 15 accounts.
### 1.3 Configure webhook URL in Razorpay Dashboard
The Webhook URL serves as a callback URL where Razorpay can send notifications or data updates to your AI agent.
1. Copy the webhook URL and the API key mentioned in the **Instructions** section of the Razorpay Integration Card. Append the region of your AI agent to the domain of the webhook url. r1/r2/r3/r4/r5 are the regions of your AI agent, you can refer the following list for the same. (r1 = MEA, r2 = Jakarta, r3 = Singapore, r4= USA, r5 = Europe)
For example, if the domain is https://cloud.yellow.ai, you need to change it to https://r1.cloud.yellow.ai if the region of the AI agent is MEA. If the AI agent belongs to India, you can use origin domain itself.
2. Log into the [Razorpay Dashboard](https://dashboard.razorpay.com/#/access/signin) and navigate to **Settings** → **Webhooks**.
3. Click **+ Add New Webhook** on the right corner.
4. In the **Webhook Setup** pop-up, enter the URL in which you'd like to receive the webhook payload when an event is triggered. We recommend using a **HTTPS URL**. Ensure you enable all the events shown in the screenshot below.
:::note
You can set upto 10 URLs to receive Webhook notifications. Webhooks can only be delivered to public URLs. If you attempt to save a localhost endpoint as part of a webhook setup, you will encounter an error.
:::
5. Enter a **Secret** for the webhook endpoint. This secret will be used to validate whether the webhook is from **RazorPay**. Do not expose this secret publicly. Click [here](https://razorpay.com/docs/webhooks/validate-test/) to know more validating webhooks.
6. In the **Alert Email** field, enter the email address to which the notifications should be sent in case there's a webhook failure.
7. Select the required events from the list of **Active Events**.
8. Click **Create Webhook**. After you set a webhook, it appears on the list of webhooks.
:::note
To modify the webhook further, you can select the webhook and click **Edit**. You can refer this [video](https://www.youtube.com/watch?v=qojkh8Vbnek) as well.
:::
## Enable Razorpay events in your AI agent
Enable Razorpay events in your AI agent to trigger flows based on event occurrences, allowing seamless integration of payment processes with AI agent functionalities.
1. In Development/Staging environment, go to **Automation** > **Event** > **Integrations**.
2. Activate the event, **Razorpay Payment Status**. Click on the more options icon and select *Activate*. If there are multiple accounts, you need to activate for each account separately.
3. A journey with its trigger point as this event should be created in **Automation**. Based on the received event data, an appropriate message will be displayed to the end user.
:::info
If you have added multiple accounts in your platform, enable events for each of those accounts.
:::
## Generate Razorpay payment Link from AI agent conversation
The following are the use-cases that are supported in this integration.
:::note
When multiple accounts are added, select the appropriate account for each node, allowing you to leverage the unique functionalities of each account for their intended purposes.
:::
1. Go to Development/Staging environment and navigate to **Automation** > **Build** > Select the flow where you want to Generate payment link.
2. Click **Add node** > **Integrations** > **Razorpay payment gateway**.
In the Automation flow builder, select the **Integrations** node and click **Razorpay** from the list of integrations that have been enabled for that AI agent.
3. In the first drop-down choose **Generate Payment Link**.
4. Configure all the required fields. The table below contains sample values, data types, and descriptions for these fields.
| Field name | Sample value| Data type |Description |
| -------- | -------- | -------- |----|
Amount|100|String| The amount that should be collected using payment link. This must be in the smallest unit of the currency. For example, if you want to receive a payment of ₹299.95, you must enter the value 29995.|
|Currency|INR|String|Default is **INR**, we also accept payments in [international currencies](https://razorpay.com/docs/payments/payments/international-payments/#supported-currencies).|
|Description|Test|String|A brief description of the payment link.|
IsUPILinkedEnabled|true|Boolean| Indicates if the payment link is a UPI payment link. **true:** A UPI payment link has been created. **false:** It is a standard payment link and not a UPI payment link. |
|CustomerObject `{ "contact": "+919999999999", "email": "gaurav.kumar@example.com", "name": "Gaurav Kumar" },` |Object|Customer details|
|Notes| `{ "policy_name": "Jeevan Bima" }`|Object|Set of key-value pairs that can be used to store additional information. You can enter a maximum of 15 key-value pairs, with each value having a maximum limit of 256 characters.|
|NotifyOptions| `{ "email": true, "sms": true }`|object|Defines who handles the payment link notifications.|
CallbackUrl |https://example-callback-url.com/ |String|if specified it adds a redirect URL to the payment link. Once a customer completes the payment, they will be redirected to the specified URL.|
|CallbackMethod|get|String| If callback_url parameter is passed, callback_method must be passed with the value get.|
|EnableRemindertrue||Boolean|This is used to send reminders for the payment link. Possible values: **true:** To send reminders. **false:** To disable reminders.
|CustomOptions | Reference details|Object|Custom options|
**Sample success response:**
```json
{
"accept_partial": false,
"amount": 1000,
"amount_paid": 0,
"callback_method": "get",
"callback_url": "https://example-callback-url.com/",
"cancelled_at": 0,
"created_at": 1591097057,
"currency": "INR",
"customer": {
"contact": "+919999999999",
"email": "gaurav.kumar@example.com",
"name": "Gaurav Kumar"
},
"description": "Payment for policy no #23456",
"expire_by": 1691097057,
"expired_at": 0,
"first_min_partial_amount": 100,
"id": "plink_ExjpAUN3gVHrPJ",
"notes": {
"policy_name": "Jeevan Bima"
},
"notify": {
"email": true,
"sms": true
},
"payments": null,
"reference_id": "TS1989",
"reminder_enable": true,
"reminders": [],
"short_url": "https://rzp.io/i/nxrHnLJ",
"status": "created",
"updated_at": 1591097057,
"user_id": ""
}
```
**Sample response in case of fallback:**
```json
{
"error": {
"code": "BAD_REQUEST_ERROR",
"description": "The api key provided is invalid",
"source": "NA",
"step": "NA",
"reason": "NA",
"metadata": {}
}
}
```
To use this **Integration Action Node** in an app.yellow.ai AI agent, refer the following example:
```js
app.executeIntegrationAction({
"integrationName": "razorpay",
"action": "Generate Payment Link - Partial Payments”,
"dynamicParams": {
"amount": "500",
"currency": "INR",
"description": "test",
"isUPILinkEnabled": true,
"customerObject": { "name": "GaurarKumar", "contact": "+919999999999", "email": "gaurav.kumar@example.com" },
"notes": {
"policy_name": "Jeevan Bima"
},
"notifyOptions": {
"sms": true,
"email": true
},
"callbackUrl": "https://example-callback-url.com/",
"callbackMethod": "get",
"enableReminder": "true",
"customOptions": {
"test":"testing"
}
}
}).then((res) => {
console.log("response from action node", res);
app.log(res, '||Response from action node||')
}).catch((err) => {
console.log("Error in action node", err);
app.log(err, '||Error in action node||')
})
```
#### Event payload for Payment status
```js
{
"id": "rfnd_FS8TWyPrCsa0OB",
"entity": "payment",
"amount": 50000,
"currency": "INR",
"payment_id": "pay_FPoJKWQQ8lK13n",
"notes": {
"comment": "Customer Notes for Webhooks."
},
"receipt": null,
"acquirer_data": {
"arn": null
},
"created_at": 1597734071,
"batch_id": null,
"status": "processed",
"speed_processed": "normal",
"speed_requested": "optimum"
}
```
### Generate Payment Link for Partial Payments
1. In the Automation flow builder, select the **Integrations** node and click **Razorpay** from the list of integrations that have been enabled for that AI agent.
2. After clicking **Razorpay**,an **Integration Action Node** will be added to the flow builder. When you click that node, you will see all use-cases of this integration in a drop-down. Choose **Generate Payment Link** from them.
3. Fill in all the mandatory fields. The below-mentioned table consists of the sample value,data type and description for all these fields.
| Field name | Sample value| Data type |Description |
| -------- | -------- | -------- |----|
| Text | Text | Text |
Amount|100|String|The amount that should be the payment link. This must be in the smallest unit of the currency. For example, if you want to receive a payment of ₹299.95, you must enter the value 29995.|
|Currency|INR|String|Default is **INR**, we also accept payments in [international currencies](https://razorpay.com/docs/payments/payments/international-payments/#supported-currencies).|
|Description|Test|String|A brief description of the payment link.|
IsUPILinkedEnabled|true|Boolean| Indicates if the payment link is a UPI payment link. **true:** A UPI payment link has been created. **false:** It is a standard payment link and not a UPI payment link. |
|CustomerObject| `{ "contact": "+919999999999", "email": "gaurav.kumar@example.com", "name": "Gaurav Kumar" },`|Object|Customer details|
|Notes| `{ "policy_name": "Jeevan Bima" }`|Object|Set of key-value pairs that can be used to store additional information. You can enter a maximum of 15 key-value pairs, with each value having a maximum limit of 256 characters.|
|NotifyOptions| `{ "email": true, "sms": true }`|object|Defines who handles the payment link notifications.|
CallbackUrl |https://example-callback-url.com/ |String|if specified it adds a redirect URL to the payment link. Once a customer completes the payment, they will be redirected to the specified URL.|
|CallbackMethod|get|String| If callback_url parameter is passed, callback_method must be passed with the value get.|
|EnableRemindertrue||Boolean|This is used to send reminders for the payment link. Possible values: **true:** To send reminders. **false:** To disable reminders.
|CustomOptions | Reference details|Object|Custom options|
|isPartialPaymentAccepted|true|Boolean|Indicates whether customers can make partial payments using the payment link. **Possible values:** **true:** Customer can make partial payments.**false (default):** Customer cannot make partial payments.|
**Sample response in case of success:**
```json
{
"accept_partial": false,
"amount": 1000,
"amount_paid": 0,
"callback_method": "get",
"callback_url": "https://example-callback-url.com/",
"cancelled_at": 0,
"created_at": 1591097057,
"currency": "INR",
"customer": {
"contact": "+919999999999",
"email": "gaurav.kumar@example.com",
"name": "Gaurav Kumar"
},
"description": "Payment for policy no #23456",
"expire_by": 1691097057,
"expired_at": 0,
"first_min_partial_amount": 100,
"id": "plink_ExjpAUN3gVHrPJ",
"notes": {
"policy_name": "Jeevan Bima"
},
"notify": {
"email": true,
"sms": true
},
"payments": null,
"reference_id": "TS1989",
"reminder_enable": true,
"reminders": [],
"short_url": "https://rzp.io/i/nxrHnLJ",
"status": "created",
"updated_at": 1591097057,
"user_id": ""
}
```
**Sample response in case of fallback:**
```json
{
"error": {
"code": "BAD_REQUEST_ERROR",
"description": "The api key provided is invalid",
"source": "NA",
"step": "NA",
"reason": "NA",
"metadata": {}
}
}
```
To use this **Integration Action Node** in an app.yellow.ai AI agent, refer the following example:
```js
app.executeIntegrationAction({
"integrationName": "razorpay",
"action": "Generate Payment Link",
"dynamicParams": {
"amount": "500",
"isPartialPaymentAccepted":true,
"currency": "INR",
"description": "test",
"isUPILinkEnabled": true,
"customerObject": { "name": "GaurarKumar", "contact": "+919999999999", "email": "gaurav.kumar@example.com" },
"notes": {
"policy_name": "Jeevan Bima"
},
"notifyOptions": {
"sms": true,
"email": true
},
"callbackUrl": "https://example-callback-url.com/",
"callbackMethod": "get",
"enableReminder": "true",
"customOptions": {
"test":"testing"
}
}
}).then((res) => {
console.log("response from action node", res);
app.log(res, '||Response from action node||')
}).catch((err) => {
console.log("Error in action node", err);
app.log(err, '||Error in action node||')
})
```
### Intiate refund
1. In the Automation flow builder, select the **Integrations** node and click **Razorpay** from the list of integrations that have been enabled for that AI agent.
2. After clicking **Razorpay**,an **Integration Action Node** will be added to the flow builder. When you click that node, you will see all use-cases of this integration in a drop-down. Choose **Generate Payment Link** from them.
3. Fill in all the mandatory fields. The below-mentioned table consists of the sample value,data type and description for all these fields.
| Field Name | Sample value | Data type |Description|
| -------- | -------- | -------- |---|
| Amount|100|String| The amount to be refunded (in the smallest unit of currency). For example, refund in INR, a value of 100 means 100 paise (equivalent to ₹1).|
|paymentId|pay_FgR9UMzgmKDJRi|String|The unique identifier of the payment for which a refund is initiated|
refundType|normal|String|Speed at which the refund should be processed. **Possible values:****normal:** Indicates that the refund will be processed at a normal speed i.e. within 5-7 working days.**optimum:** Indicates that the refund will be processed at an optimal speed based on Razorpay's internal fund transfer logic. If the refund has to be processed instantly, **Razorpay** will do so irrespective of the payment method. If an instant refund is not possible, Razorpay will initiate a refund at the normal speed. For example, in case of payments made using debit cards, netbanking or unsupported credit cards.
notes|{}|object|Key-value store for storing your reference data. A maximum of 15 key-value pairs can be included.|
4. The **Generate Payment Link Integration Action** Node has two outcomes, success or failure. Based on the success/failure of the execution of the **Integration Action Node**, the flow will proceed to **success** or **fallback** branches respectively.
**Success Response:**
```js
{
"id": "rfnd_FgRAHdNOM4ZVbO",
"entity": "refund",
"amount": 10000,
"currency": "INR",
"payment_id": "pay_FgR9UMzgmKDJRi",
"notes": {
"notes_key_1": "Beam me up Scotty.",
"notes_key_2": "Engage"
},
"receipt": null,
"acquirer_data": {
"arn": "10000000000000"
},
"created_at": 1600856650,
"batch_id": null,
"status": "processed",
"speed_processed": "normal",
"speed_requested": "normal"
}
```
To use this **Integration Action Node** in an app.yellow.ai AI agent, refer the following example:
```js
app.executeIntegrationAction({
"integrationName": "razorpay",
"action": "Generate Payment Link",
"dynamicParams": {
"amount": "500",
"refundType":"normal",
"paymentId":"pay_FgR9UMzgmKDJRi",
"notes": {
"policy_name": "Jeevan Bima"
}
}
}).then((res) => {
console.log("response from action node", res);
app.log(res, '||Response from action node||')
}).catch((err) => {
console.log("Error in action node", err);
app.log(err, '||Error in action node||')
})
```
---
## Salesforce messaging
:::info
This legacy Chat product will be deprecated on February 14, 2026, and is currently in maintenance mode. While existing implementations will continue to function, we strongly recommend that you avoid setting up new chat channels.
You can use Salesforce Messaging instead.
:::
Integrating Salesforce messaging with Yellow.ai allows you to connect with live agents for query resolution.
**Key benefits of integrating Salesforce messaging with Yellow.ai**:
* **Live agent support** – Use the Salesforce Messaging app to connect with live agents directly within the chatbot interface for real-time query resolution.
* **Live chat management** – Agents can easily accept and manage chat requests within the Salesforce platform. Once the agent is connected, the chat session is displayed within the Salesforce interface for efficient communication.
* **Enhanced customer experience** – Improves customer support by enabling live agent interactions and faster query resolution.
#### Prerequisites
Before proceeding with the integration, ensure that the Salesforce administrator provides the following details to the Integrations team:
* Organization ID
* Developer Name
* Organization Base URL
## Connect Salesforce messaging with Yellow.ai
To integrate Salesforce messaging with Yellow.ai, follow these steps:
1. Login to the [Yellow platform](https://cloud.yellow.ai/) and navigate to the **Development** environment.
* In a two-tier environment, you can only add accounts in the Development environment.
* In a three-tier environment, you can only add accounts in Staging/Sandbox environment.
2. Go to **Extensions** > **Integrations** > **Live chat** > **Salesforce messaging**.
3. In **Give account name**, enter a unique name using only lowercase alphanumeric characters and underscores (_).
4. In **Organization Id**, enter the unique identifier of your Salesforce organization.
5. In **Developer Name**, enter the identifier for the specific deployment within your organization.
6. In the **Organization Base URL**, enter the API endpoint of your Salesforce organization (example, `https://t-ct--fulluat.sandbox.my.salesforce-scfd.com`).
7. In **Customise chat headers**, enable this option to personalize bot headers with agent names and descriptions. The original settings will be restored once the ticket is closed.
7. Click **Connect**.
* To connect more accounts, repeat the steps outlined above for each account. You can add a maximum of 15 accounts.
## Connect bot users to live agents on Salesforce
This integration enables bot users to connect with live agents on the Salesforce platform directly from your Yellow.ai account.
1. In the Automation flow builder, select the **Raise Ticket** node.
2. Select **Salesforce messaging** from the **Live chat agent** drop-down.
3. In **Account name**, select the appropriate Salesforce account.
The following table contains the details of each field in the **Raise ticket** node.
| Field name | Sample value | Data type |Description
| -------- | -------- | -------- |-----|
|Message after ticket assignment| Requesting live agent connection | String | Message will be displayed to the user once a ticket is assigned to an agent.|
|Name| Rio | String |Name of the user|
|Mobile| 9870000000| String| Mobile number of the user|
Email|test@gmail.com| String | Email address of the user
Query| I have a concern regarding my flight ticket|String| Subject/topic/reason why the ticket was created|
Salesforce messaging custom fields|
|Array| List of details provided by the user before initiating the chat with the live agent|
## Handle chat sessions in Salesforce
1. To manage live chat interactions, ensure that agents are available on Salesforce platform to accept chat requests from users. Once connected, the chat session will be displayed within the Salesforce interface.
2. To end the chat, the agent needs to close the chat tab, which will automatically trigger the ticket-closed event on the Yellow.ai platform, marking the session as completed.
---
## Salesforce CRM
Salesforce is a cloud-based software company that provides a range of business solutions. At its core, Salesforce offers Customer Relationship Management (CRM) software, which helps businesses manage and analyze customer interactions and data. The CRM system allows companies to track sales, marketing efforts, customer service, and other aspects of their operations.
In addition to CRM, Salesforce has various subsidiaries and products that extend its capabilities. For instance, they offer live chat solutions to facilitate real-time customer support and engagement. Yellow.ai supports integration with Salesforce CRM and [Salesforce Live Chat](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/salesforcelivechat).
:::note
To configure Salesforce CRM, the user account must have Super Admin–level permissions.
:::
## Table of contents
1. [What Salesforce actions are available on Yellow.ai?](#salesforce-actions-that-can-be-managed-from-yellowai)
2. [How to connect Salesforce CRM with Yellow.ai?](#connect-salesforce-crm-with-yellowai)
3. [How to use Salesforce CRM from Yellow.ai?](#manage-your-salesforce-crm-through-bot-conversations)
## Salesforce actions that can be managed from yellow.ai
After integrating with Salesforce CRM, you can perform the following tasks directly from the Yellow.ai platform:
| Action | Description |
|---------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|
| createRecord | Creates a record in the integrated Salesforce account. The following are the different types of available records: 1. Accounts2. Contacts3. Opportunities4. Leads5. Cases6. Campaigns7. Products and Price Books8. Tasks9. Events10. Custom11. Objects12. Documents and Attachments |
| updateRecord | Updates a record in the integrated Salesforce account. |
| searchRecord | Looks for a particular info in the integrated Salesforce account. |
| Query by SQL | Query and retrieve data from the Salesforce database. You can create SQL queries by referring to the following links: [Link 1](https://trailhead.salesforce.com/content/learn/modules/apex_database/apex_database_soql) [Link 2](https://developer.salesforce.com/docs/atlas.en-us.soql_sosl.meta/soql_sosl/sforce_api_calls_soql.htm) |
| Get User Details by Owner ID | In Salesforce, each user has a unique identifier known as the Owner Id. This process involves using the Owner Id of a record (e.g., Account, Contact, or Opportunity) to fetch details about the user who owns that particular record. |
## Connect Salesforce CRM with Yellow.ai
**Prerequisites:**
1. An active Salesforce CRM account
2. An active yellow.ai account
3. Super Admin access
To connect your Salesforce CRM account with Yellow.ai, follow these steps:
1. On the left navigation bar, go to **Extensions** > **Integrations**.
2. Navigate to **CRM** > **Salesforce CRM**. Alternatively, you can use the Search box to find the integration app.
3. Choose a unique name for your Salesforce account and select the Salesforce CRM environment. It is recommended to use a name that reflects its purpose for improved usability.
4. Click **Connect**. You will see a pop-up screen to login with a list of accounts.
5. Choose the respective account and click **Log in**
6. If you have multiple accounts, click **+Add account** and follow the above mentioned steps to add each one. You can add a maximum of 15 accounts.
:::note
1. In a two-tier environment, such as bots with only Development/Live environments, you can add account names only in the development mode. Once added and flows have been built, in the Live mode, you can only choose the account names and not edit them.
2. In a three-tier environment, such as bots with Staging/Sandbox/Production modes, in Staging and Sandbox modes, you can add and edit new accounts. However, in Production, only the account details added in Staging will be available. You can only map in the production environment.
:::
## Manage your Salesforce CRM through bot conversations
To carry out a certain action in your Salesforce account, follow these steps:
1. Go to **Automation** and [create a flow](https://docs.yellow.ai/docs/platform_concepts/studio/build/Flows/journeys#2-create-a-flow) based on your requirement.
2. In whichever point you want the bot to access Salesforce, include the Salesforce CRM node. For that, drag the node connector, go to **Integrations** > **Salesforce CRM**.
3. In the Salesforce CRM node, fill in the following
* **Account name:** Choose the preferred Salesforce CRM account.
* **Action:** Choose the action to be performed.
* **Select Objects:** Choose the Salesforce CRM object in which the chosen action should be performed.
* Depending on the selected object, the corresponding fields will be shown. To collect this information from users, you must construct the flow accordingly and [store the data in variables](https://docs.yellow.ai/docs/platform_concepts/studio/build/bot-variables#41-store-data-in-variables). These variables will then be used in this context.
4. Each Salesforce action returns a response as a JSON object or an array. [Store that response in a variable](https://docs.yellow.ai/docs/platform_concepts/studio/build/bot-variables#41-store-data-in-variables) and [pass that variable](https://docs.yellow.ai/docs/platform_concepts/studio/build/bot-variables#42-retrieve-data-from-variables) in a [message node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/message-nodes1/message-nodes) to display that response to the end user.
| Action | Syntax |
|--------------------------------------------------------------------|-------------------------------------------------------------------------------------------|
| To consume the JSON object as it is | `{{variables.variable_name_object.choices.0.text}}` |
| To access fields in JSON object response | `{{variables.variable_name.field_name}}` |
| To access array values| Use keys. For instance, to access the weather description from the below response, use `{{variables.API_var.weather.0.description}}` because the value is inside an array and is the first value (0th index).|
**Sample response:**
```
{
"coord": {
"lon": 77.2167,
"lat": 28.6667
},
"weather": [
{
"id": 761,
"main": "Dust",
"description": "dust",
"icon": "50d"
}
],
}
```
#### Supported Version
This integration will support the latest version's (52.0) releases. For more information on this, please click [here](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/api_rest_eol.htm).
---
## Salesforce Live Chat
Yellow.ai’s integration with [Salesforce](https://www.salesforce.com/in/) lets you connect with the live chat agents of **Salesforce** to resolve your queries.
:::note
Agents must remain available (online) on Salesforce (when queue management and offline support are not configured).
:::
## Connect Salesforce with Yellow.ai
In a two-tier environment, you can connect an integration app in the Development environment. In a three-tier environment, you can connect the integration app either in Staging or Sandbox. All connected integrations are available in the live environment.
To connect your yellow.ai account with **Salesforce**, follow these steps.
1. On the left navigation bar, go to **Extensions** > **Integrations** > **Live chat** > **Salesforce live chat**.
2. Search for **Salesforce Live Chat** or choose the category named **Live chat** from the left navigation bar, and then click on **Salesforce Live Chat**.
3. In **Give account name**, enter a unique name for the integration. You can use only lowercase alphanumeric characters and underscores (`_`).
Fill in the required fields.
4. In **Organization Id**, enter the unique identifier of the Salesforce account that represents a particular organization. To fetch this, refer to the following steps:
a. Login to your Salesforce account.
b. Click on the app launcher and choose **Service Console**.
c. Click on the setup button at the top right corner and select **Setup**.
d. In the **Quick Find** section, search for **Deployments** in the **Chat** section.
e. Click on the deployment that is already created (if not, create a deployment).
f. In the deployment script, locate an ID starting with **00D**, which is the Organization ID.
4. In **Deployment Id**, enter the identifier for the specific deployment within your organization. To fetch this, refer to the following steps:
a. Login to your Salesforce account.
b. Click on the app launcher and choose **Service Console**.
c. Click on the setup button at the top right corner and select **Setup**.
d. In the **Quick Find** section, search for **Deployments** in the **Chat** section.
e. Click on the deployment that is already created (if not, create a deployment).
f. In the deployment script, locate an ID **not starting with 00D**, which is the Deployment ID.
5. In **Button Id**, enter the unique identifier for the chat button that initiates a live chat session. Ensure that the agent is available with the Button ID you are configuring for the integration to connect successfully. To obtain this ID, follow these steps:
a. Login to your Salesforce account.
b. Click on the app launcher and choose **Service Console**.
c. Click on the setup button at the top right corner and select **Setup**.
d. In the **Quick Find** section, search for **Chat Buttons and Invitations** in the **Chat** section.
e. Click on the button that is already created (if not, create a button).
f. In the **Chat Button Code**, locate an ID starting with **573**, which is the Button ID.
6. In **Organization Base URL**, enter the chat API endpoint of a particular salesforce organization. To fetch this, refer to the following steps:
a. Login to your Salesforce account.
b. Click on the app launcher and choose **Service Console**.
c. Click on the setup button at the top right corner and select **Setup**.
d. In the **Quick Find** section, search for **Chat Settings** in the Chat section.
e. Find the **Chat API Endpoint** present and copy the URL value till **.com**. This is your Organization Base URL.
7. In **Agent device**, specify the type of device the agent will use (e.g., desktop, mobile)
8. In **Agent screen resolution**, enter the screen resolution of the agent's device to ensure optimal chat interface display. Example: For desktop, it could be 2560 x 1600.
9. Configure other details:
Option | Description
------ | -----------
**Language** | Language preferred by the user to chat with the live agent.
**Agent Timeout** | The time duration (in minutes) after which an agent will be timed out if inactive. Default Value: 5 minutes
**Enable queue updates** | Enable this for users to receive updates on their position in the queue during chat interactions.
**Enable sticky agent** | Enable this option to assign chats to a specific agent based on the agent ID provided in the Raise Ticket.
**Disconnect chat from** | Enable this to immediately close tickets for users waiting in the queue but not yet assigned to an agent.
**Send queue updates event to** | Enable this to inform users about their queue position with real-time updates sent as events to the bot, allowing developers to customize bot flows based on the queue status.
**Customise chat headers** | Enable this to personalize the bot headers with agent names and descriptions. The bot headers will be restored ot original settings once the ticket is closed.
10. Once you're done, click **Connect**.
11. If you have multiple accounts, click on **+ Add account** and follow the above mentioned steps to add each of them. You can add a maximum of 15 accounts.
## Connect bot users to live agents on Salesforce
This integration lets you connect with live agents on the **Salesforce** platform from your yellow.ai account.
:::note
- When multiple accounts are added, select the appropriate account for each node, allowing you to leverage the unique functionalities of each account for their intended purposes.
- During the testing process, agents should be **online** for the specific button ID or group mapped in the configuration.
:::
:::info
Use **Ticket-closed** in the **Raise Ticket node** to perform specific actions when a live chat closes, instead of using the **ticket-close** event.
:::
1. In the Automation flow builder, select the **Raise Ticket** node.
2. Select **Salesforce Live Chat** from the **Live chat agent** drop-down list.
### Raise Ticket Node — Field Details
| Field Name | Sample Value | Data Type | Description |
|-----------------------------------|----------------------------------------------------------------------------------------------------------------------|-----------|---------------------------------------------------------------------------------------------------------------------|
| Message after ticket assignment | Requesting live agent connection. | String | The message that will be displayed to the end user after a ticket is successfully assigned to an agent |
| Name | Rajesh | String | Name of the user |
| Mobile | 9870000000 | String | Mobile number of the user |
| Email | test@gmail.com | String | Email address of the user |
| Query | I have a concern regarding my flight ticket | String | The subject/topic/reason why the ticket was created |
| Salesforce Live Chat Custom Fields | ```json [ { "label": "Mobile", "value": "...", "transcriptFields": [...] }, { "label": "Chat", "value": "...", "transcriptFields": [...] } ] ``` | Array | The list of details provided by the user before initiating the chat with the live agent |
| Salesforce Live Chat Custom Entities | ```json [ { "entityName": "Contact", "saveToTranscript": "contact", ... } ] ``` | Array | The records created/searched depending on what `[EntityFieldsMaps](...)` has enabled |
| Agent ID | agent_12345 | String | Unique ID of the agent to assign to the bot user. Applies only when Sticky Agent option is enabled |
**Advanced options**
### Advanced Options – Field Details
| Field Name | Sample Value | Data Type | Description |
|-----------|--------------|-----------|-------------|
| Message after agent assignment | `You are now connected to {{liveAgent}}.` | String | Message shown to the end user when an agent is assigned. Use `{{liveAgent}}` to display the agent's name. |
| Language preference | English | String | Language preferred by the end user to chat with the live agent. |
| Message to display queue position | `Your queue position is {{position}}` | String | Message shown when the ticket is in queue. Use `{{position}}` to show current queue position. |
| Message to display updated queue position | `Your current queue position is {{position}}` | String | Message shown when queue position updates. Use `{{position}}` to display the latest position. |
| Message after agent transfer | `Your chat has been transferred to {{liveAgent}}` | String | Message shown when chat is transferred. Use `{{liveAgent}}` to show new agent's name. |
| Message to display estimated wait time before agent assignment | `The estimated wait time for the chat to get assigned is {{waitTime}} seconds` | String | Notifies user about estimated wait time. Use `{{waitTime}}` to display the duration. |
| Display agent name | true | Boolean | When enabled, displays the chat agent’s name on assignment or transfer. |
| Warning message to display after end user inactivity | Idle warning | String | Message displayed if the user is inactive. |
| Timeout message to display after end user inactivity | Idle timeout | String | Message shown when live chat ends due to user inactivity. |
| Message after failure in establishing connection | Connection failure | String | Message shown when there is a failure connecting to a live agent. |
| Message after agent has disconnected from the chat | Agent has disconnected | String | Message shown when agent disconnects. If no other agent is available, the fallback message from "failure in establishing connection" is used. |
| Message to display after chat ends due to agent inactivity | Agent timeout occurred | String | Message shown when agent exceeds the configured inactivity threshold. |
| Send chat transcript | **True** or **False** | Boolean | Whether to send conversation history to the agent. Pass **True** to send, **False** to skip. |
:::note
**For "Send chat transcript":**
If the entire transcript exceeds Salesforce's single message character limit, it will be split and sent as multiple messages.
For example:
If the transcript is **8000 characters** and the limit is **4000**, it will be sent as **two packets** of 4000 characters each.
:::
|
**Sample success response**
```json
{
"assignedTo": true,
"success": true,
"status": "ASSIGNED",
"ticketInfo": "{{apiresponse}}"
}
```
:::note
apiresponse represents the raw response from the Salesforce create ticket API
:::
**Sample failure response**
```json
{
"success": false,
"assignedTo": false,
"agentNotAvailable": true,
"message": "TicketId is not created and transferring the control back to the bot",
"ticketInfo": "{{apiresponse}}"
}
```
## Steps to set up bot in Salesforce Live Chat
1. Login to your [Salesforce account](https://login.salesforce.com/?locale=in) and click **Setup**
2. On the left side bar search, search for **Visualforce Pages** and click on it.
3. Click **New** to create a new VF page.
4. Perform the following actions:
* Enter the **Label**,**name** and check the **Available for Lightning. Experience, Experience Builder sites, and the mobile app** option.
* Paste the embedded bot code into the markups section between the tags.
* Click **Save**.
5. Go back to the left side bar search and search for **App Manager** and click it.
6. Scroll down to **Service Console** and click **Edit**.
7. Click **Utility items(Desktop only)** and click **Add Utility Item**.
8. Select **VisualForce** from the drop-down.
9. Perform the following actions in the following page.
* Add **Label** , **Icon**, **Panel Width**, **Panel Height**.
* Under **Component Properties** deselect **Show Label**.
* In **Visualforce Page Name**, add the name of the VF page created in **step 4**.
* Click **Save**.
10. Go to **App launcher** and navigate to Service Console. You should see the bot at the bot footer.
### Reference
[Salesforce Chat REST API Resources](https://developer.salesforce.com/docs/atlas.en-us.live_agent_rest.meta/live_agent_rest/live_agent_rest_API_requests.htm)
---
## SAML integration for AI agent
SAML (Security Assertion Markup Language) authentication allows you to authenticate users during their conversations with our AI agent. It ensures that only logged-in users can access specific journeys, such as viewing calendars, personal records, or restricted enterprise information.
This guide explains how to configure SAML authentication for your AI agent, including prerequisites, mandatory fields, session management, and the authentication flow.
## When to Use SAML Authentication
Use SAML authentication if you want to:
* Restrict AI agent access to authenticated users only.
* Enable single sign-on (SSO) with any identity provider.
## Prerequisites
Before configuring SAML authentication, ensure that you have:
* An active identity provider (IdP) such as Azure AD, Okta, or JumpCloud.
* Admin access to configure an application on the IdP.
* Access to the following details from your IdP:
* **Authorization URL** (IdP SSO login endpoint)
* **IdP Certificate** (X.509 certificate, usually downloadable from IdP metadata)
* **Audience**
## Configure SAML for AI agent authentication
### 1. Create a SAML Application in Your IdP
1. Log in to your identity provider (Azure, Okta, JumpCloud, etc.).
2. Create a new SAML application.
3. Add the following configuration values in the IdP:
* **Redirect URI**: Provide the AI agents [Redirect URI](#add-redirection-uri).
* **Audience**: Use the Audience value provided by the agent platform.
4. Download the **IdP Certificate** or copy it from the metadata.
### 2. Configure your SAML in the Yellow.ai cloud platform
1. Switch to development (Sandbox/Staging) environment, go to **Extensions** > **Integrations** > **Tools & utilities**.
2. Click **Generic SAML**. You can also use the search bar to find the integration.
3. Fill in the following mandatory fields:
* **Account name** – A unique identifier for this SAML setup (e.g., "AzureSSO").
* **Authorization URL** – The IdP login endpoint.
* **IdP certificate** – Paste the X.509 certificate from the IdP.
* **Audience** – Enter the unique identifier for the Service Provider (SP). This is a crucial security field that specifies the application this SAML assertion is intended for. The application will reject any assertion where the Audience URI does not match its own ID. This value is provided by the SP and is often a URL. (It is typically a URL or a Uniform Resource Name (URN), such as `https://yourapp.com/saml/metadata` or `urn:google:workspace`.)
* **Session expiry (in hours)**: Set how long a user’s authenticated session remains valid. After the session expires, users will be prompted to re-authenticate via SAML before continuing restricted conversation flows. Default value is 3 hours and maximum value is 6 hours.
4. Click **Connect**.
## Add Redirection URI
The **Redirection URI** is the endpoint on our AI agent platform where the identity provider (IdP) sends the authentication response after a user logs in. This URI is to ensure that the authentication handshake is completed successfully.
1. On the **Generic SAML Integration** configuration page, click the **Redirection URI** displayed on the right to copy it.
2. Add this URI to your **Identity Provider (IdP) configuration**. This step is mandatory—authentication will not succeed unless the Redirect URI is registered with the IdP.
**Example format**:
```
https://r6.cloud.yellow.ai/api/galaxy/genericsaml
```
## Adding Redirect URI to Your Identity Provider (IdP)
After copying the **Redirect URI** from the Generic SAML Integration page, you must add it to your IdP configuration. This ensures the IdP knows where to send authentication responses after a user successfully signs in.
:::note
The **Redirect URI differs by region and environment**.
Make sure you copy the URI directly from your **Generic SAML Integration configuration page** in the platform.
Do not reuse values from another environment (e.g., staging vs. production) or region, as authentication will fail if mismatched.
:::
### Azure Active Directory (Azure AD)
1. Sign in to the [Azure portal](https://portal.azure.com).
2. Navigate to **Azure Active Directory** > **Enterprise Applications**.
3. Select your application or create a new one for the AI agent.
4. Under **Manage**, go to **Single sign-on** > **Basic SAML Configuration**.
5. In the **Reply URL (Assertion Consumer Service URL)** field, paste the copied Redirect URI.
6. Save the configuration.
### Okta
1. Sign in to the [Okta Admin Console](https://admin.okta.com).
2. Go to **Applications** > **Applications** and select your app.
3. Under the **General** tab, click **Edit**.
4. In the **Single sign-on URL** field, paste the Redirect URI.
5. Save the changes.
### JumpCloud
1. Sign in to the [JumpCloud Admin Portal](https://console.jumpcloud.com).
2. Navigate to **User Authentication** > **SSO Applications**.
3. Select your app or create a new SAML app.
4. In the **ACS URL (Assertion Consumer Service URL)** field, paste the Redirect URI.
5. Save the configuration.
---
## Enable SAML success and failure events
After integrating SAML, it is important to track whether authentication attempts succeed or fail. To ensure your AI agent is notified of the authentication status, enable the `generic-saml-success` and `generic-saml-failure` events.
To enable:
1. Go to **Automation** > **Events** > **Integration**
2. Search for the SAML events mentioned above.
* `generic-saml-success`: Triggered when the SAML authentication request completes successfully.
* `generic-saml-failure`: Triggered when the SAML authentication request fails.
3. Click the **More options** icon and select **Enable**.
---
## Add SAML Authentication in your agent Flow
Once SAML configuration is complete, you can enable authentication in your agent flow as explained below:
1. Navigate to the specific Flow where you want to add authentication process.
2. In the agent flow, add an **Integration** node and select **Generic SAML**.
3. Choose the **Account name** associated with your SAML configuration.
4. In the **Action** field, you can set one of the following:
* **Check user session** – Verifies if the user is already logged in.
* **Generate SAML request** – Initiates a new authentication request.
5. In **Parse API response**, choose the desired function (needed only if you want the AI agent to automatically extract and process values from the SAML response).
:::note
You can write custom functions to process success and failure events. The authentication response is passed to the AI agent through the `{{{data}}}` object variable. In your function, you can extract details such as authentication status, error messages, or user attributes and use them to guide the conversation flow or handle fallbacks.
:::
---
### Troubleshooting
| Issue | Possible Cause | Resolution |
| -------------------------------- | ------------------------------------ | ------------------------------------------------------------- |
| Authentication fails immediately | You will see proper reason in Failure event | Ensure Redirect URI matches in both IdP and AI agent configuration |
| Certificate validation error | Expired or incorrect IdP Certificate | Download a fresh certificate from the IdP |
| Users logged out too soon | Short session expiry configured | Increase session expiry up to 6 hours |
| AI agent not redirecting | Missing Check User Session node, Redirect URI mismatch | Ensure the flow includes session validation |
---
## SAP Cloud For Customers (SAP IO)
Yellow.ai Integration with SAP.io allows you to seamlessly connect your SAP cloud instance with the yellow.ai platform.
With this integration, you can seamlessly connect their SAP instance with yellow.ai by providing the user name, password and the instance base URL. This connector will enable users to receive events for SAP objects. Furthermore, this connector will enable you to take actions, such as create, update, get and delete the tickets.
Action | Description
------ | ------------
Create Service Request | Creates a new service request.
Update Service Request | Updates an existing service request.
Get Service Request | Retrieves details of a service request.
Delete Service Request | Deletes a service request.
:::note
This integration will support the latest version releases. For more details, click [here](https://help.sap.com/doc/d0f9ba822c08405da7d88174b304df84/CLOUD/en-US/index.html).
:::
## Integrating SAP for cloud customers with your bot
In a two-tier environment, you can connect an integration app in the Development environment. In a three-tier environment, you can connect the integration app either in Staging or Sandbox. All connected integrations are available in the live environment.
To connect SAP with yellow.ai, follow these steps:
1. Switch to Development/Staging environment and go to **Extensions** > **Integrations** > **ITSM** > **SAP for cloud customers**.
2. In **Give account name**, enter a unique name for the integration. You can use only lowercase alphanumeric characters and underscores (`_`).
3. In **Username** and **Password**, enter your SAP cloud account's login credentials.
4. In **SAP base URL**, enter your account's domain URL.
5. Click **Connect**.
6. To connect another account, click **+Add Account** and proceed with the previous steps. You can add a maximum of 15 accounts.
## Accessing SAP Functions through Bot Conversation
The SAP integration enables bot to perform various actions. These include creating new records, reading, updating, and deleting existing records.
:::note
In cases with multiple accounts, you can select which account to use for accessing a specific action.
:::
On-click the SAP cloud for customers node, and you can customize the object and action type along with the attributes you wish to pass.
---
## ServiceNow Integration
## ServiceNow integration overview
The ServiceNow integration with Yellow.ai allows your AI agent to manage IT service requests and streamline service desk operations directly through conversations. With this integration, your bot can create, update, and retrieve ServiceNow tickets, helping teams handle incidents more efficiently and maintain consistent service experiences.
| Action | Description |
|-------------------------|-----------------------------------------------------|
| Create ticket | Create a ticket in ServiceNow. |
| Update ticket | Update a ticket in ServiceNow. |
| Search ticket | Search for a ticket in ServiceNow. |
| Upload file | Upload a file to ServiceNow. |
| Get file | Fetch a file from ServiceNow. |
| Get File list | Fetch a file list from ServiceNow. |
| Get Category | Retrieves the list of available categories from your ServiceNow instance. A category represents a high-level classification of a service request or incident|
| Get Sub Category | Fetches the sub-categories related to a selected category in ServiceNow. A sub-category represents a specific classification under a selected category|
## Connect ServiceNow with Yellow.ai
Create an app on ServiceNow to fetch instance URL, client ID and client secret and input the details in Yellow.ai to establish this integration.
### Create an app on ServiceNow
1. Go to your **ServiceNow** instance, search for **Application Registry** in the **Filter Navigator**.
2. Go to **New** (on the top right corner) and click **Create an OAuth API endpoint for external clients** to create an application.
3. Fill in the following fields:
* **Name**: Enter a unique name for your application.
* **Redirect URL**: Click the lock icon to open the field and add this [Redirect URL](https://cloud.yellow.ai/integration/oauth/serviceNow).
* **Accessible from**: Choose **All Application Scopes** and click **Submit**.
4. Once the app is created, it will get listed as shown below. Click on it.
5. Copy the **Instance URL** (the URL on the address bar of your Service now account(as shown below), **Client ID** and **Client Secret**. To copy the client secret, click the lock icon and then copy.
### Connect your ServiceNow accout with Yellow.ai
This section guides you through linking your ServiceNow instance with Yellow.ai. Once connected, your AI agent can interact with your ServiceNow environment to manage service requests, fetch details, and automate routine IT support tasks.
:::note
In a two-tier environment, you can connect an integration app in the Development environment. In a three-tier environment, you can connect the integration app either in Staging or Sandbox. All connected integrations are available in the live environment.
:::
1. Switch to the Development/Staging environment and go to **Extensions** > **Integrations** > **ITSM** > **Service Now**.
2. In **Give account name**, provide a name for the integration. You can use only lowercase alphanumeric characters and underscores (_).
3. Copy and paste the **Instance URL**, **Client ID** and **Client Secret** (as mentioned in the previous section)
4. Click **Connect**.
5. You will be prompted to grant authorization, click **Allow**.
7. To connect another account, click +Add Account and proceed with the previous steps. You can add a maximum of 15 accounts.
:::info
1. In a two-tier environment, add account names in Development and use them in Live.
2. In a three-tier environment, add accounts in Staging and Sandbox, and they'll be available in Production.
:::
## Manage ServiceNow actions from AI agent conversations
From Yellow.ai you can access your ServiceNow instance and create, update and search a ticket, upload,get file and file list.
1. Go to **Automation** and [create a flow](https://docs.yellow.ai/docs/platform_concepts/studio/build/Flows/journeys#2-create-a-flow) that suits your use case.
2. Go to the specific point in the conversation where you want to add the node. Click **Add Node**, then go to **Integrations** and select **ServiceNow**.
3. Configure the node using the available options.
4. In **Account name**, xhoose the account to use for accessing a specific action.
5. In **Action:**, select the action to perform.
| **Action** | **Description** | **Live Example in Bot Conversation** |
|-----------------------|------------------|--------------------------------------|
| **Create Ticket** | Creates a new incident or service request in ServiceNow. Use this when users report an issue. | 🗨️ *“My laptop won’t boot.”* 🤖 *“I’ve created a ticket for you — #INC78901. Our IT team will get back to you shortly.”* |
| **Update Ticket** | Updates an existing ticket with new information, such as a status change, comment, or additional notes. | 🗨️ *“The issue still persists even after restarting.”* 🤖 *“Got it. I’ve updated ticket #INC78901 with your latest comment.”* |
| **Search Ticket** | Searches ServiceNow for tickets based on filters like status, priority, or keywords. | 🗨️ *“Can you show me my open requests?”* 🤖 *“You currently have 2 open tickets: #INC78901 and #INC78902.”* |
| **Upload File** | Attaches a file to a specified ticket. Common for logs, error screenshots, or policy documents. | 🗨️ *“Here’s the screenshot of the error.”* 📎 *(User uploads file)* 🤖 *“Thanks! I’ve uploaded this to ticket #INC78901.”* |
| **Get File List** | Returns a list of all files attached to a specific ticket. | 🗨️ *“Did I attach the policy PDF to my ticket?”* 🤖 *“Ticket #INC78901 has the following files: policy_doc.pdf, error_log.txt.”* |
| **Get File** | Retrieves a specific file from a ticket. | 🗨️ *“Please show me the error log I uploaded.”* 🤖 *“Here it is: [error_log.txt]”* (link or file preview) |
| **Get Category** | Retrieves a list of available issue categories. | 🤖 *“Please select a category for your issue: Hardware, Software, Network.”* |
| **Get Sub Category** | Fetches subcategories based on a selected category. | 🗨️ *“I selected ‘Hardware’.”* 🤖 *“Please choose a sub-category: Laptop, Printer, Monitor.”* |
6. **Select Objects:** Choose the object (**Incident**/**Request**) in which the chosen action should be performed. **Get File** action is an exception, the **Select Objects** field doesn't apply to this action.
7. Once you choose the object, the corresponding fields for that action and object is displayed. Fill these fields by adding nodes before the ServiceNow node to collect user information, or click 'Or' to manually input the details.
To collect the information from user, add a [prompt node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#docusaurus_skipToContent_fallback) and [store the response in a variable](https://docs.yellow.ai/docs/platform_concepts/studio/build/bot-variables#store-data-in-variables). Pass that variable in the respective field.
* **Parse API response:** Select the function that will parse the API response(optional). To know more about how to use this, click [here](https://docs.yellow.ai/docs/platform_concepts/studio/api/send-receive-apiresponses#parse-api-responses).
4. [Store the API response in a variable](https://docs.yellow.ai/docs/platform_concepts/studio/build/bot-variables#store-data-in-variables) and pass it in a [message node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/message-nodes1/message-nodes) to display the response to the end user.
## Configuring AI Agent for a sample Service Now use case
Let's say that you want to fetch a ticket's information in **Requests** using the ticket number.
1. Add a [prompt node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-nodes#docusaurus_skipToContent_fallback) and collect the ticket number value in a variable.
2. Include the **ServiceNow** node wherever you want the bot to access ServiceNow and click the node.
* **Account name:** Choose the **ServiceNow** account in which you want to perform this action.
* **Action:** Choose **Search Ticket**.
* **Select Objects:** Choose **Requests**.
* **Select Fields:** Choose the field based on which you want to search. Here it's **Number**.
* **Value:** Pass the variable which contains the number value (from step 1). You can also click **Or** and type the value if it is a static value.
* **Parse API response:** Select the function that will parse the API response(optional). To know more about how to use this, click [here](https://docs.yellow.ai/docs/platform_concepts/studio/api/send-receive-apiresponses#parse-api-responses). Store the response in a variable.
3. Use a [message node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/message-nodes1/message-nodes) and pass this variable in it to display this response to the end user.
**Alternative**:
You can also [store the API response in a variable](https://docs.yellow.ai/docs/platform_concepts/studio/build/bot-variables#store-data-in-variables) and use a syntax in a message node to display certain info from the API response. Refer to this [article](https://docs.yellow.ai/docs/platform_concepts/studio/api/add-api-apinode#display-api-response) for syntaxes.
For example, you can use ``{{{variables.variablename.result.0.number}}}`` to retrieve the ticket number from the following response.
```json
{
"result": {
"sys_updated_on": "2021-11-12 14:16:35",
"task_effective_number": "INC0010005",
"number": "INC0010005",
"sys_updated_by": "admin",
"opened_by": {
"link": "https://dev61928.service-now.com/api/now/table/sys_user/6816f79cc0a8016401c5a33be04be441",
"value": "6816f79cc0a8016401c5a33be04be441"
},
"sys_created_on": "2021-11-12 14:16:35",
"sys_domain": {
"link": "https://dev61928.service-now.com/api/now/table/sys_user_group/global",
"value": "global"
},
"state": "1",
"sys_created_by": "admin",
"knowledge": "false",
"opened_at": "2021-11-12 14:16:35",
"short_description": "This is short description",
"description": "Hardware Name : Dell Inspiron 27 7790nRequester Name : Shubhi SaxenanColor : Dark Black",
"close_notes": "",
"sys_class_name": "incident",
"closed_by": "",
"sys_id": "e788251187333010fc0763150cbb358c",
"incident_state": "1",
"urgency": "2",
"severity": "3",
"approval": "not requested",
"upon_approval": "proceed",
"category": "inquiry"
}
}
```
---
## Service now live chat
Yellow.ai seamlessly integrates with ServiceNow live chat, allowing you to connect your live agents from ServiceNow live chat with Yellow.ai. When a user seeks assistance from a live support agent, they'll be directly connected to ServiceNow's live agent through our platform.
## Connect ServiceNow live in Yellow.ai
To integrate ServiceNow live on yellow.ai, follow these steps:
:::note
Agents should have AWA agent roles for accessing agent workspace.
:::
1. Go to the ServiceNow's [devloper portal](https://developer.servicenow.com/dev.do#!/home) and click on your profile picture.
2. Click **Activate Plugin** under **Instance action**.
3. Search for **Glide Virtual Agent** and click **Activate** next to it.
4. Once your plugin gets activated, click **Start building**.
5. Go to **All** > search for **System Application** and click **All** under **Automation**.
6. In the following screen search for **Virtual Agent API** and click **Install**.
7. Once the installation is complete, create a **Service Channel** for the agents to handle user chats from Service Now. Go to **All** > **Advanced Work Assignment** > **Service Channels** > **New**. Click [here](https://docs.servicenow.com/en-US/bundle/vancouver-servicenow-platform/page/administer/advanced-work-assignment/task/awa-create-service-channel.html) for a detailed guide on creating service channels.
8. Create a queue criteria for the chats to route to the agent. Go to **All** > **Advanced Work Assignment** > **Settings** > **Queues** > **New**. Click [here](https://docs.servicenow.com/en-US/bundle/vancouver-servicenow-platform/page/administer/advanced-work-assignment/task/awa-create-queue.html) for a detailed guide on creating queues.
9. To add webhook URL, go to **System Mailboxes**> **Outbound** > **REST Messages** > **VA Bot to Bot**.
10. To enable authentication in Servicenow APIs go to **System web services** > **Scripted REST APIs** > **VA Bot Integration** > **Resource tab** > **Require**.
11. Add trusted domains in **System Tables** > **Provider Channel Identity** > **VA Bot to Bot Provider Application**. For example, yellow.ai, yellowmessenger.com
12. Go to **All** > **System OAuth** > **Application Registry** > **New** > **Create an OAuth API endpoint for external clients**.
13. In the **Redirect URL** field, copy the redirect url from the inetgration section of yellow.ai and paste it here. To copy it from yellow.ai, go to cloud.yellow.ai > **Integrations** > search for **ServiceNow Live** > click **Redirect URL** (refer image below)
14. In **Accessible from** field, choose **All Application Scopes** and click **Submit**.
15. After it gets saved, click on the created app and copy the **Client ID** and **Client secret**.
16. Go to cloud.yellow.ai > **Integrations** > search for **ServiceNow Live**.
17. Fill in the following fields
* **Give account name:** Provide a unique name to your account.
* **Instance URL**: Enter your Service now instance URL.
* **Client Id** and **Client Secret**: Paste the **Client ID** and **Client Secret** of your **ServiceNow** account from step 12.
15. Click **Connect**.
:::info
You can add a maximum of 15 accounts. Follow the above mentioned steps to add multiple accounts.
:::
## Activate ServiceNow events in Yellow.ai
To inform the bot about specific events in ServiceNow, you must enable these events within Yellow.ai. By doing so, you can configure the bot to take specific actions in response to these events.
The following are the events available for ServiceNow in Yellow.ai
| Events | Descriptions |
|-----------------------------------|--------------------------------------------------------|
| servicenow-agent-joined | When a support agent in ServiceNow accepts the chat request |
| ticket-closed | When agents in ServiceNow close tickets due to bot user inactivity |
| servicenowlivechat_agent_messages | When a live agent messages the bot user |
| servicenow-conversation-ended | When the live agent ends the conversation with the user |
To activate these events:
1. Go to **Automation** > **Event** > **Integrations** > search for **ServiceNow**.
2. Click the ellipsis button and click **Activate** on the respective events.
## Connect users to ServiceNow Live Agents
:::info
Use **Ticket-closed** in the **Raise Ticket node** to perform specific actions when a live chat closes, instead of using the **ticket-close** event.
:::
You need to build a flow that redirects your users to the ServiceNow agents and the agent needs to close the chat to end the chat in ServiceNow.
1. Go to **Automation** and [build a flow](https://docs.yellow.ai/docs/platform_concepts/studio/build/Flows/journeys) based on your requirement.
2. Insert the **Integration node** wherever you want the flow to connect the user to the ServiceNow agent. To do so, drag and drop a [Raise ticket node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/raise-ticket) and choose the integrated ServiceNow account in the **Live chat agent** drop down.
3. Fill in the following fields in the node. The variables chosen for these fields must be previously collect in the flow via node. To know more about this in detail, click [here](https://docs.yellow.ai/docs/platform_concepts/studio/build/bot-variables#41-store-data-in-variables).
| Field name | Sample value | Data type |Description
| -------- | -------- | -------- |-----|
|Pre-Agent Assignment Message|Requesting live agent connection.|String| The message that will be displayed to the end user after a ticket is successfully assigned to an agent|
|Name| Rajesh|String|Name of the end user|
|Mobile| 9870000000| String|Mobile number of the end user|
Email|test@gmail.com|String|Email address of the end user
Query|I have a concern regarding my flight ticket|String| The subject/topic/reason why the ticket was created|
Priority|MEDIUM|String|The priority of the ticket|
You can enable **Advanced Options** to access the advanced features of this node.
4. Once you have set up the flow, chats will get automatically forwarded to live agents on Service now live chat when this flow gets triggered.
---
## SFTP integration
Use SFTP integration to securely sync and manage user data with your platform. This setup allows you to transfer files from your server to sync with **User 360**, enabling you to view and analyze user data in one place.
To connect an SFTP server:
1. In Development/Staging environment, go to **Extensions** > **Integration** and search for the *SFTP* app.
2. Click **+Add account**.
3. In **Give account name**, enter a unique name for the account. Use only lowercase alphanumeric characters and underscores (_) with a limit of 20 characters. Example value: `support_team_account`.
4. In **Host IP**, enter the IP address of your SFTP server. Example: `192.168.1.1`
5. In **Port**, enter the port number used for SFTP connection. Default: `22`
6. In **Username**, enter your SFTP server username.
7. Enable **Private key based authentication** if you want to authenticate with a private SSH key instead of uploading your SFTP account password. See [Private key setup](#private-key-setup) for how to obtain the key and allow access on your server.
8. In **Password**, enter the associated SFTP password. Applicable only if **Private key based authentication** is disabled.
### Private key setup {#private-key-setup}
If you do not want to use a password, enable **Private key based authentication** (step 7) and reach out to our team at [support@yellow.ai](mailto:support@yellow.ai) for the SSH key material. Support will provide the **private key** to configure in the Yellow.ai SFTP integration and the matching **public key** for your SFTP server.
On your SFTP host, only the **public key** must be trusted (never put the private key in `authorized_keys` or share it outside your organization). Add Yellow.ai’s public key for the SFTP user so the platform can connect without a password.
To add Yellow.ai’s public key on your remote SFTP server, you can follow these steps (run as the SFTP user or adjust paths if your server uses a different home layout):
```bash
# on remote system (SFTP user home or account used for this integration)
mkdir -p .ssh
nano .ssh/authorized_keys
# append Yellow.ai's public key as one line (e.g. ssh-ed25519 or ssh-rsa ...)
chmod 600 .ssh/authorized_keys
chmod 700 .ssh
```
### Sync SFTP data with User 360
Once the connection is established, you can enable automatic syncing of user data by turning on the **Sync SFTP with user 360 and view users’ data in your user 360** option.
This allows the system to regularly import user information from your SFTP server, keeping your User 360 view up to date with the latest data.
Learn more about [user data import through SFTP](https://docs.yellow.ai/docs/platform_concepts/engagement/cdp/user_data/sync_users).
---
## Shopify
## 1. Introduction
Shopify is an e-commerce platform that lets merchants worldwide to build and customize online stores to sell theor products. Integrating Shopify with Yellow.ai enables seamless access to Shopify data within our platform. This integration facilitates data utilization for effective campaigns, event management, and enhanced customer support.
**Here are some key benefits of leveraging this integration**:
* **Unified customer data & customer self-serve**: Gain a 360-degree view of your customers by integrating their Shopify data with other touchpoints. You can enable customers to access their data and order details conveniently through bot conversations.
* **Personalized campaigns and automated workflows**: Leverage customer data to create targeted marketing campaigns, boost sales and create automated workflows.
* **Better support with multi-channel**: Provide better customer support by accessing order history and customer details directly from Shopify and interact across various channels, including chat, email, Whatsapp and more.
* **Time and Cost Saving**s: Reduce manual data entry, streamline processes, and save time and resources by automating tasks.
## 2.Integrate Shopify with Yellow.ai
### Step 1: Create a Shopify app in the developer portal
1. Open the Shopify developer portal and create a new app for your store.
2. Give the app a clear name (for example, "Yellow.ai Integration") and save it.
3. In the app settings, open **Versions** and click **Create version**.
4. In **Redirect URLs**, add `https://cloud.yellow.ai/integration/oauth/shopify_v2` and save the version.
5. From the app page, click **Install** to install the app in your Shopify admin.
### Step 2: Collect the credentials you will use in Yellow.ai
You will need three values from Shopify. Keep them handy before you connect the integration:
Option | What it means | How to find it
------ | ------------- | -------------
**shopName** | Your store's myshopify subdomain. | Open Shopify Admin → **Settings** → **Domains** and copy the `.myshopify.com` URL. If it is `https://acme-store.myshopify.com/admin`, then `shopName = acme-store`.
**clientId** | The app's Client ID. | In the developer portal, open your app → **Settings** and copy the Client ID.
**clientSecret** | The app's Client Secret. | In the developer portal, open your app → **Settings** and copy the Client Secret.
### Step 3: Connect the Shopify app to Yellow.ai
1. Login to [yellow.ai platform](https://cloud.yellow.ai/).
2. Go to **Integrations** > **Retail & ecommerce** > **Shopify shop**. Alternatively, you can use the Search box to find the integration app.
3. To **Add account**, fill in the required details.
Option | Description
------ | -----------
**Give account name** | Provide a name for the Shopify account you want to connect.
**Shop Name** | Enter the `shopName` you noted earlier (the part before `.myshopify.com`).
**Client ID** | Paste the `clientId` from the developer portal settings.
**Client Secret** | Paste the `clientSecret` from the developer portal settings.
**Subscription topics** | Choose the events you want to receive, such as customer creation or order updates. These events appear in the [Events](https://docs.yellow.ai/docs/platform_concepts/studio/events/event-hub) section of Yellow.ai.
**Domain name** | Enter the full store domain, such as `acme-store.myshopify.com`, so Yellow can ingest store events for User 360.
4. Click **Connect**.
If the integration is successful, you will see the **Shopify Shop** app on the **Integrations** page.
:::note
* Please ensure that you enter your store name exactly as it appears in your Shopify account.
* For the initial user backfilling of the recent 10k user data, please reach out to the team to initiate the process.
:::
***
## 3. Shopify user data syncing in User 360/Engage
This integration automates the creation of user records in User 360 using Shopify event data. By default, it is configured to capture userIds, emails, and phone numbers. Additionally, the integration enables the automatic synchronization of the following event data with User 360. This empowers User 360 as a valuable resource for personalized and effective user engagement strategies.
:::note
Shopify events will be generated only from the store channel and passed to User 360. If event tracking is enabled in the bot, these events will also be sent to the bot. Events originating from other channels, such as orders created through a bot or WhatsApp, will generally not be relayed unless the user profile exists in User 360.
:::
### Supported standard user properties from Shopify events
The following standard user properties are automatically added or updated in User 360 directly from Shopify events.
* userId
* email
* firstName
* phone
* city
* country
### Supported Shopify events syncing in User 360
The integration enables the automatic synchronization of the following event data with User 360. This empowers User 360 as a valuable resource for personalized and effective user engagement strategies.
The following table provides a comprehensive list of Shopify events along with their descriptions and sample use cases.
| Event | Description | Sample use cases |
|--------|----------------|----------------------|
| shopifyNewOrder | A new order is created in the Shopify store. | Trigger order confirmation email or update inventory when a new order is created in your Shopify store. |
| shopifyNewProduct | A new product has been added to the Shopify store. | Update product catalog, create product listings, or send a WhatsApp notification when a new product is added to your Shopify store. |
| shopifyOrderCancelled | An order is cancelled. | Handle order cancellation: Update inventory levels, refund payments, or notify customers when their orders are canceled. |
| shopifyOrderFulfilled | An order was fulfilled or completed. | Update shipping information, send shipping notifications to the customer, or update order status when an order is fulfilled or completed. |
| shopifyOrderPaid | Payment made for an order. | Send payment receipt, or update financial record when a payment is made for an order. |
| shopifyRefundCreated | A refund was created for an order. | Update financial records, notify customers about their refund, or adjust inventory levels when a refund is issued for an order. |
| shopifyReturnRequest | A return request is initiated. | Helpful for handling return-related processes, such as notifying customers and managing inventory. |
| shopifyNewCustomer | A new customer is registered. | Add the customer to User 360, send welcome email, or track customer acquisition when a new customer registers in your Shopify store. |
| shopifyCustomerUpdate | A customer’s profile details have been updated. | Keep your customer database up to date or send profile change notification when a customer's profile details are updated. |
| shopifyCheckoutCreated| Order checkout is initiated in Shopify. | Track order progress when an order checkout is initiated in your Shopify store. |
| shopifyOrdersUpdated | Shopify order is updated. | Monitor order changes, adjust inventory, or notify the customer on order updates to handle order updates in Shopify store. |
| shopifyCartCreate | A cart is created in Shopify. | Track shopping cart activity, gather data on abandoned carts, or initiate cart-related marketing efforts when a cart is created in Shopify store. |
:::note
To know how to run campaigns based on Shopify events, see [here](#run-campaigns-based-on-shopify-events).
:::
### Payload samples of Shopify events in User 360
The following are the event schemas associated with various Shopify events. These event schemas define the structure and data that get sent to the CDP when specific events occur in your Shopify store.
**From SDK**
```js
{
"token": "c1-830e691d16f1093cfcde75960320d9cd",
"note": "",
"attributes": {},
"original_total_price": 3000,
"total_price": 3000,
"total_discount": 0,
"total_weight": 0,
"item_count": 1,
"items": [
{
"id": 43453026762901,
"properties": {},
"quantity": 1,
"variant_id": 43453026762901,
"key": "43453026762901:159c30471db14672fe636da24f9346f2",
"title": "Adania Pant - Black",
"price": 3000,
"original_price": 3000,
"discounted_price": 3000,
"line_price": 3000,
"original_line_price": 3000,
"total_discount": 0,
"discounts": [],
"sku": "",
"grams": 0,
"vendor": "twewr",
"taxable": true,
"product_id": 7907558064277,
"product_has_only_default_variant": false,
"gift_card": false,
"final_price": 3000,
"final_line_price": 3000,
"url": "/products/adania-pant?variant=43453026762901",
"featured_image": {
"aspect_ratio": 0.714,
"alt": "Adania Pant",
"height": 2048,
"url": "https://cdn.shopify.com/s/files/1/0458/0252/0725/files/2015-03-30_Jake_Look_16_20656_16533.jpg?v=1684943817",
"width": 1462
},
"image": "https://cdn.shopify.com/s/files/1/0458/0252/0725/files/2015-03-30_Jake_Look_16_20656_16533.jpg?v=1684943817",
"handle": "adania-pant",
"requires_shipping": true,
"product_type": "",
"product_title": "Adania Pant",
"product_description": "\\nThis is a demonstration store. You can purchase products like this from Baby & Company\\nSuper stretch Adaina Pant offers the classic skinny with all the fun bits. Zip closure at back with concealed zip openings at ankles. By Malene Birger. Color Blue. 90% Polyamide, 10% Elastane. Made in China. Ashley is wearing a European 36. ",
"variant_title": "Black",
"variant_options": [
"Black"
],
"options_with_values": [
{
"name": "Color",
"value": "Black"
}
],
"line_level_discount_allocations": [],
"line_level_total_discount": 0,
"quantity_rule": {
"min": 1,
"max": null,
"increment": 1
},
"has_components": false
}
],
"requires_shipping": true,
"currency": "INR",
"items_subtotal_price": 3000,
"cart_level_discount_applications": [],
"userId": "x1660667398488_WIv23Iv-fr-McW_SZme-l"
}
```
```js
{
"id": 35481578373269,
"token": "3d58ad45d661cd34d882fda5c68a36b8",
"cart_token": "c1-830e691d16f1093cfcde75960320d9cd",
"email": null,
"gateway": null,
"buyer_accepts_marketing": false,
"buyer_accepts_sms_marketing": false,
"sms_marketing_phone": null,
"created_at": "2023-09-22T12:13:51+00:00",
"updated_at": "2023-09-22T08:13:59-04:00",
"landing_site": "/",
"note": "",
"note_attributes": [],
"referring_site": "",
"shipping_lines": [],
"shipping_address": [],
"taxes_included": false,
"total_weight": 0,
"currency": "INR",
"completed_at": null,
"phone": null,
"customer_locale": "en-IN",
"line_items": [
{
"key": "43453026762901",
"fulfillment_service": "manual",
"gift_card": false,
"grams": 0,
"presentment_title": "Adania Pant",
"presentment_variant_title": "Black",
"product_id": 7907558064277,
"quantity": 1,
"requires_shipping": true,
"sku": "",
"tax_lines": [
{
"position": 1,
"price": "2.70",
"rate": 0.09,
"title": "CGST",
"source": "Shopify",
"compare_at": null,
"zone": "country",
"channel_liable": false,
"identifier": null
}
],
"taxable": true,
"title": "Adania Pant",
"variant_id": 43453026762901,
"variant_title": "Black",
"variant_price": "30.00",
"vendor": "twewr",
"unit_price_measurement": {
"measured_type": null,
"quantity_value": null,
"quantity_unit": null,
"reference_value": null,
"reference_unit": null
},
"compare_at_price": null,
"line_price": "30.00",
"price": "30.00",
"applied_discounts": [],
"destination_location_id": null,
"user_id": null,
"rank": null,
"origin_location_id": null,
"properties": null
}
],
"name": "#35481578373269",
"abandoned_checkout_url": "https://twewr.myshopify.com/45802520725/checkouts/ac/c1-830e691d16f1093cfcde75960320d9cd/recover?key=a745691198001ff07b2f08d7233541a8",
"discount_codes": [],
"tax_lines": [
{
"price": "2.70",
"rate": 0.09,
"title": "CGST"
}
],
"presentment_currency": "INR",
"source_name": "web",
"total_line_items_price": "30.00",
"total_tax": "2.70",
"total_discounts": "0.00",
"subtotal_price": "30.00",
"total_price": "32.70",
"total_duties": "0.00",
"device_id": null,
"user_id": null,
"location_id": null,
"source_identifier": null,
"source_url": null,
"source": null,
"closed_at": null
}
```
```json
{
"id": 5159806763157,
"admin_graphql_api_id": "gid://shopify/Order/5159806763157",
"app_id": 580111,
"browser_ip": "49.43.249.107",
"buyer_accepts_marketing": false,
"cancel_reason": null,
"cancelled_at": null,
"cart_token": "c1-830e691d16f1093cfcde75960320d9cd",
"checkout_id": 35481578373269,
"checkout_token": "3d58ad45d661cd34d882fda5c68a36b8",
"client_details": {
"accept_language": "en-IN",
"browser_height": null,
"browser_ip": "49.43.249.107",
"browser_width": null,
"session_hash": null,
"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/116.0.0.0 Safari/537.36"
},
"closed_at": null,
"company": null,
"confirmation_number": "XPLMPXRME",
"confirmed": true,
"contact_email": "tom@gmail.com",
"created_at": "2023-09-22T08:14:46-04:00",
"currency": "INR",
"current_subtotal_price": "30.00",
"current_subtotal_price_set": {
"shop_money": {
"amount": "30.00",
"currency_code": "INR"
},
"presentment_money": {
"amount": "30.00",
"currency_code": "INR"
}
},
"current_total_additional_fees_set": null,
"current_total_discounts": "0.00",
"current_total_discounts_set": {
"shop_money": {
"amount": "0.00",
"currency_code": "INR"
},
"presentment_money": {
"amount": "0.00",
"currency_code": "INR"
}
},
"current_total_duties_set": null,
"current_total_price": "30.00",
"current_total_price_set": {
"shop_money": {
"amount": "30.00",
"currency_code": "INR"
},
"presentment_money": {
"amount": "30.00",
"currency_code": "INR"
}
},
"current_total_tax": "0.00",
"current_total_tax_set": {
"shop_money": {
"amount": "0.00",
"currency_code": "INR"
},
"presentment_money": {
"amount": "0.00",
"currency_code": "INR"
}
},
"customer_locale": "en-IN",
"device_id": null,
"discount_codes": [],
"email": "tom@gmail.com",
"estimated_taxes": false,
"financial_status": "paid",
"fulfillment_status": null,
"landing_site": "/",
"landing_site_ref": null,
"location_id": null,
"merchant_of_record_app_id": null,
"name": "#1085",
"note": null,
"note_attributes": [],
"number": 85,
"order_number": 1085,
"order_status_url": "https://twewr.myshopify.com/45802520725/orders/24a0946393b4889192c0d7056751e889/authenticate?key=c60f3a72f52578b00cc7cb8551811cbc",
"original_total_additional_fees_set": null,
"original_total_duties_set": null,
"payment_gateway_names": [
"bogus"
],
"phone": null,
"po_number": null,
"presentment_currency": "INR",
"processed_at": "2023-09-22T08:14:43-04:00",
"reference": "6925f7d584e825b7f3fdbf5de7b3a5e1",
"referring_site": "",
"source_identifier": "6925f7d584e825b7f3fdbf5de7b3a5e1",
"source_name": "web",
"source_url": null,
"subtotal_price": "30.00",
"subtotal_price_set": {
"shop_money": {
"amount": "30.00",
"currency_code": "INR"
},
"presentment_money": {
"amount": "30.00",
"currency_code": "INR"
}
},
"tags": "",
"tax_exempt": false,
"tax_lines": [],
"taxes_included": false,
"test": true,
"token": "24a0946393b4889192c0d7056751e889",
"total_discounts": "0.00",
"total_discounts_set": {
"shop_money": {
"amount": "0.00",
"currency_code": "INR"
},
"presentment_money": {
"amount": "0.00",
"currency_code": "INR"
}
},
"total_line_items_price": "30.00",
"total_line_items_price_set": {
"shop_money": {
"amount": "30.00",
"currency_code": "INR"
},
"presentment_money": {
"amount": "30.00",
"currency_code": "INR"
}
},
"total_outstanding": "0.00",
"total_price": "30.00",
"total_price_set": {
"shop_money": {
"amount": "30.00",
"currency_code": "INR"
},
"presentment_money": {
"amount": "30.00",
"currency_code": "INR"
}
},
"total_shipping_price_set": {
"shop_money": {
"amount": "0.00",
"currency_code": "INR"
},
"presentment_money": {
"amount": "0.00",
"currency_code": "INR"
}
},
"total_tax": "0.00",
"total_tax_set": {
"shop_money": {
"amount": "0.00",
"currency_code": "INR"
},
"presentment_money": {
"amount": "0.00",
"currency_code": "INR"
}
},
"total_tip_received": "0.00",
"total_weight": 0,
"updated_at": "2023-09-22T08:14:47-04:00",
"user_id": null,
"billing_address": {
"first_name": null,
"address1": "Chennai",
"phone": "90909 09090",
"city": "Chennai",
"zip": "600012",
"province": "Tamil Nadu",
"country": "India",
"last_name": "Baid",
"address2": "Chennai",
"company": null,
"latitude": 13.098633,
"longitude": 80.2596083,
"name": "Baid",
"country_code": "IN",
"province_code": "TN"
},
"customer": {
"id": 6989864763541,
"email": "tom@gmail.com",
"accepts_marketing": false,
"created_at": "2023-09-22T08:14:44-04:00",
"updated_at": "2023-09-22T08:14:46-04:00",
"first_name": null,
"last_name": "Baid",
"state": "disabled",
"note": null,
"verified_email": true,
"multipass_identifier": null,
"tax_exempt": false,
"phone": null,
"email_marketing_consent": {
"state": "not_subscribed",
"opt_in_level": "single_opt_in",
"consent_updated_at": null
},
"sms_marketing_consent": null,
"tags": "",
"currency": "INR",
"accepts_marketing_updated_at": "2023-09-22T08:14:44-04:00",
"marketing_opt_in_level": null,
"tax_exemptions": [],
"admin_graphql_api_id": "gid://shopify/Customer/6989864763541",
"default_address": {
"id": 8320474546325,
"customer_id": 6989864763541,
"first_name": null,
"last_name": "Baid",
"company": null,
"address1": "Chennai",
"address2": "Chennai",
"city": "Chennai",
"province": "Tamil Nadu",
"country": "India",
"zip": "600012",
"phone": "90909 09090",
"name": "Baid",
"province_code": "TN",
"country_code": "IN",
"country_name": "India",
"default": true
}
},
"discount_applications": [],
"fulfillments": [],
"line_items": [
{
"id": 12623712354453,
"admin_graphql_api_id": "gid://shopify/LineItem/12623712354453",
"fulfillable_quantity": 1,
"fulfillment_service": "manual",
"fulfillment_status": null,
"gift_card": false,
"grams": 0,
"name": "Adania Pant - Black",
"price": "30.00",
"price_set": {
"shop_money": {
"amount": "30.00",
"currency_code": "INR"
},
"presentment_money": {
"amount": "30.00",
"currency_code": "INR"
}
},
"product_exists": true,
"product_id": 7907558064277,
"properties": [],
"quantity": 1,
"requires_shipping": true,
"sku": "",
"taxable": true,
"title": "Adania Pant",
"total_discount": "0.00",
"total_discount_set": {
"shop_money": {
"amount": "0.00",
"currency_code": "INR"
},
"presentment_money": {
"amount": "0.00",
"currency_code": "INR"
}
},
"variant_id": 43453026762901,
"variant_inventory_management": "shopify",
"variant_title": "Black",
"vendor": "twewr",
"tax_lines": [],
"duties": [],
"discount_allocations": []
}
],
"payment_terms": null,
"refunds": [],
"shipping_address": {
"first_name": null,
"address1": "Chennai",
"phone": "90909 09090",
"city": "Chennai",
"zip": "600012",
"province": "Tamil Nadu",
"country": "India",
"last_name": "Baid",
"address2": "Chennai",
"company": null,
"latitude": 13.098633,
"longitude": 80.2596083,
"name": "Baid",
"country_code": "IN",
"province_code": "TN"
},
"shipping_lines": [
{
"id": 4303065809045,
"carrier_identifier": "650f1a14fa979ec5c74d063e968411d4",
"code": "Standard",
"discounted_price": "0.00",
"discounted_price_set": {
"shop_money": {
"amount": "0.00",
"currency_code": "INR"
},
"presentment_money": {
"amount": "0.00",
"currency_code": "INR"
}
},
"phone": null,
"price": "0.00",
"price_set": {
"shop_money": {
"amount": "0.00",
"currency_code": "INR"
},
"presentment_money": {
"amount": "0.00",
"currency_code": "INR"
}
},
"requested_fulfillment_service_id": null,
"source": "shopify",
"title": "Standard",
"tax_lines": [],
"discount_allocations": []
}
]
}
```
```js
{
"id": 820982911946154500,
"admin_graphql_api_id": "gid://shopify/Order/820982911946154508",
"app_id": null,
"browser_ip": null,
"buyer_accepts_marketing": true,
"cancel_reason": "customer",
"cancelled_at": "2021-12-31T19:00:00-05:00",
"cart_token": null,
"checkout_id": null,
"checkout_token": null,
"closed_at": null,
"confirmed": false,
"contact_email": "jon@example.com",
"created_at": "2021-12-31T19:00:00-05:00",
"currency": "USD",
"current_subtotal_price": "398.00",
"current_subtotal_price_set": {
"shop_money": {
"amount": "398.00",
"currency_code": "USD"
},
"presentment_money": {
"amount": "398.00",
"currency_code": "USD"
}
},
"current_total_discounts": "0.00",
"current_total_discounts_set": {
"shop_money": {
"amount": "0.00",
"currency_code": "USD"
},
"presentment_money": {
"amount": "0.00",
"currency_code": "USD"
}
},
"current_total_duties_set": null,
"current_total_price": "398.00",
"current_total_price_set": {
"shop_money": {
"amount": "398.00",
"currency_code": "USD"
},
"presentment_money": {
"amount": "398.00",
"currency_code": "USD"
}
},
"current_total_tax": "0.00",
"current_total_tax_set": {
"shop_money": {
"amount": "0.00",
"currency_code": "USD"
},
"presentment_money": {
"amount": "0.00",
"currency_code": "USD"
}
},
"customer_locale": "en",
"device_id": null,
"discount_codes": [],
"email": "jon@example.com",
"estimated_taxes": false,
"financial_status": "voided",
"fulfillment_status": "pending",
"gateway": null,
"landing_site": null,
"landing_site_ref": null,
"location_id": null,
"merchant_of_record_app_id": null,
"name": "#9999",
"note": null,
"note_attributes": [],
"number": 234,
"order_number": 1234,
"order_status_url": "https://jsmith.myshopify.com/548380009/orders/123456abcd/authenticate?key=abcdefg",
"original_total_duties_set": null,
"payment_gateway_names": [
"visa",
"bogus"
],
"phone": null,
"presentment_currency": "USD",
"processed_at": null,
"processing_method": "",
"reference": null,
"referring_site": null,
"source_identifier": null,
"source_name": "web",
"source_url": null,
"subtotal_price": "388.00",
"subtotal_price_set": {
"shop_money": {
"amount": "388.00",
"currency_code": "USD"
},
"presentment_money": {
"amount": "388.00",
"currency_code": "USD"
}
},
"tags": "",
"tax_lines": [],
"taxes_included": false,
"test": true,
"token": "123456abcd",
"total_discounts": "20.00",
"total_discounts_set": {
"shop_money": {
"amount": "20.00",
"currency_code": "USD"
},
"presentment_money": {
"amount": "20.00",
"currency_code": "USD"
}
},
"total_line_items_price": "398.00",
"total_line_items_price_set": {
"shop_money": {
"amount": "398.00",
"currency_code": "USD"
},
"presentment_money": {
"amount": "398.00",
"currency_code": "USD"
}
},
"total_outstanding": "398.00",
"total_price": "388.00",
"total_price_set": {
"shop_money": {
"amount": "388.00",
"currency_code": "USD"
},
"presentment_money": {
"amount": "388.00",
"currency_code": "USD"
}
},
"total_shipping_price_set": {
"shop_money": {
"amount": "10.00",
"currency_code": "USD"
},
"presentment_money": {
"amount": "10.00",
"currency_code": "USD"
}
},
"total_tax": "0.00",
"total_tax_set": {
"shop_money": {
"amount": "0.00",
"currency_code": "USD"
},
"presentment_money": {
"amount": "0.00",
"currency_code": "USD"
}
},
"total_tip_received": "0.00",
"total_weight": 0,
"updated_at": "2021-12-31T19:00:00-05:00",
"user_id": null,
"billing_address": {
"first_name": "Steve",
"address1": "123 Shipping Street",
"phone": "555-555-SHIP",
"city": "Shippington",
"zip": "40003",
"province": "Kentucky",
"country": "United States",
"last_name": "Shipper",
"address2": null,
"company": "Shipping Company",
"latitude": null,
"longitude": null,
"name": "Steve Shipper",
"country_code": "US",
"province_code": "KY"
},
"customer": {
"id": 115310627314723950,
"email": "john@example.com",
"accepts_marketing": false,
"created_at": null,
"updated_at": null,
"first_name": "John",
"last_name": "Smith",
"state": "disabled",
"note": null,
"verified_email": true,
"multipass_identifier": null,
"tax_exempt": false,
"phone": null,
"email_marketing_consent": {
"state": "not_subscribed",
"opt_in_level": null,
"consent_updated_at": null
},
"sms_marketing_consent": null,
"tags": "",
"currency": "USD",
"accepts_marketing_updated_at": null,
"marketing_opt_in_level": null,
"tax_exemptions": [],
"admin_graphql_api_id": "gid://shopify/Customer/115310627314723954",
"default_address": {
"id": 715243470612851200,
"customer_id": 115310627314723950,
"first_name": null,
"last_name": null,
"company": null,
"address1": "123 Elm St.",
"address2": null,
"city": "Ottawa",
"province": "Ontario",
"country": "Canada",
"zip": "K2H7A8",
"phone": "123-123-1234",
"name": "",
"province_code": "ON",
"country_code": "CA",
"country_name": "Canada",
"default": true
}
},
"discount_applications": [],
"fulfillments": [],
"line_items": [
{
"id": 866550311766439000,
"admin_graphql_api_id": "gid://shopify/LineItem/866550311766439020",
"fulfillable_quantity": 1,
"fulfillment_service": "manual",
"fulfillment_status": null,
"gift_card": false,
"grams": 567,
"name": "IPod Nano - 8GB",
"price": "199.00",
"price_set": {
"shop_money": {
"amount": "199.00",
"currency_code": "USD"
},
"presentment_money": {
"amount": "199.00",
"currency_code": "USD"
}
},
"product_exists": true,
"product_id": 632910392,
"properties": [],
"quantity": 1,
"requires_shipping": true,
"sku": "IPOD2008PINK",
"taxable": true,
"title": "IPod Nano - 8GB",
"total_discount": "0.00",
"total_discount_set": {
"shop_money": {
"amount": "0.00",
"currency_code": "USD"
},
"presentment_money": {
"amount": "0.00",
"currency_code": "USD"
}
},
"variant_id": 808950810,
"variant_inventory_management": "shopify",
"variant_title": null,
"vendor": null,
"tax_lines": [],
"duties": [],
"discount_allocations": []
},
{
"id": 141249953214522980,
"admin_graphql_api_id": "gid://shopify/LineItem/141249953214522974",
"fulfillable_quantity": 1,
"fulfillment_service": "manual",
"fulfillment_status": null,
"gift_card": false,
"grams": 567,
"name": "IPod Nano - 8GB",
"price": "199.00",
"price_set": {
"shop_money": {
"amount": "199.00",
"currency_code": "USD"
},
"presentment_money": {
"amount": "199.00",
"currency_code": "USD"
}
},
"product_exists": true,
"product_id": 632910392,
"properties": [],
"quantity": 1,
"requires_shipping": true,
"sku": "IPOD2008PINK",
"taxable": true,
"title": "IPod Nano - 8GB",
"total_discount": "0.00",
"total_discount_set": {
"shop_money": {
"amount": "0.00",
"currency_code": "USD"
},
"presentment_money": {
"amount": "0.00",
"currency_code": "USD"
}
},
"variant_id": 808950810,
"variant_inventory_management": "shopify",
"variant_title": null,
"vendor": null,
"tax_lines": [],
"duties": [],
"discount_allocations": []
}
],
"payment_details": {
"credit_card_bin": null,
"avs_result_code": null,
"cvv_result_code": null,
"credit_card_number": "•••• •••• •••• 1234",
"credit_card_company": "Visa",
"buyer_action_info": null,
"credit_card_name": null,
"credit_card_wallet": null,
"credit_card_expiration_month": null,
"credit_card_expiration_year": null
},
"payment_terms": null,
"refunds": [],
"shipping_address": {
"first_name": "Steve",
"address1": "123 Shipping Street",
"phone": "555-555-SHIP",
"city": "Shippington",
"zip": "40003",
"province": "Kentucky",
"country": "United States",
"last_name": "Shipper",
"address2": null,
"company": "Shipping Company",
"latitude": null,
"longitude": null,
"name": "Steve Shipper",
"country_code": "US",
"province_code": "KY"
},
"shipping_lines": [
{
"id": 271878346596884000,
"carrier_identifier": null,
"code": null,
"delivery_category": null,
"discounted_price": "10.00",
"discounted_price_set": {
"shop_money": {
"amount": "10.00",
"currency_code": "USD"
},
"presentment_money": {
"amount": "10.00",
"currency_code": "USD"
}
},
"phone": null,
"price": "10.00",
"price_set": {
"shop_money": {
"amount": "10.00",
"currency_code": "USD"
},
"presentment_money": {
"amount": "10.00",
"currency_code": "USD"
}
},
"requested_fulfillment_service_id": null,
"source": "shopify",
"title": "Generic Shipping",
"tax_lines": [],
"discount_allocations": []
}
]
}
```
```js
{
"id": 5159806763157,
"admin_graphql_api_id": "gid://shopify/Order/5159806763157",
"app_id": 580111,
"browser_ip": "49.43.249.107",
"buyer_accepts_marketing": false,
"cancel_reason": null,
"cancelled_at": null,
"cart_token": "c1-830e691d16f1093cfcde75960320d9cd",
"checkout_id": 35481578373269,
"checkout_token": "3d58ad45d661cd34d882fda5c68a36b8",
"client_details": {
"accept_language": "en-IN",
"browser_height": null,
"browser_ip": "49.43.249.107",
"browser_width": null,
"session_hash": null,
"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/116.0.0.0 Safari/537.36"
},
"closed_at": null,
"company": null,
"confirmation_number": "XPLMPXRME",
"confirmed": true,
"contact_email": "tom@gmail.com",
"created_at": "2023-09-22T08:14:46-04:00",
"currency": "INR",
"current_subtotal_price": "30.00",
"current_subtotal_price_set": {
"shop_money": {
"amount": "30.00",
"currency_code": "INR"
},
"presentment_money": {
"amount": "30.00",
"currency_code": "INR"
}
},
"current_total_additional_fees_set": null,
"current_total_discounts": "0.00",
"current_total_discounts_set": {
"shop_money": {
"amount": "0.00",
"currency_code": "INR"
},
"presentment_money": {
"amount": "0.00",
"currency_code": "INR"
}
},
"current_total_duties_set": null,
"current_total_price": "30.00",
"current_total_price_set": {
"shop_money": {
"amount": "30.00",
"currency_code": "INR"
},
"presentment_money": {
"amount": "30.00",
"currency_code": "INR"
}
},
"current_total_tax": "0.00",
"current_total_tax_set": {
"shop_money": {
"amount": "0.00",
"currency_code": "INR"
},
"presentment_money": {
"amount": "0.00",
"currency_code": "INR"
}
},
"customer_locale": "en-IN",
"device_id": null,
"discount_codes": [],
"email": "tom@gmail.com",
"estimated_taxes": false,
"financial_status": "paid",
"fulfillment_status": null,
"landing_site": "/",
"landing_site_ref": null,
"location_id": null,
"merchant_of_record_app_id": null,
"name": "#1085",
"note": null,
"note_attributes": [],
"number": 85,
"order_number": 1085,
"order_status_url": "https://twewr.myshopify.com/45802520725/orders/24a0946393b4889192c0d7056751e889/authenticate?key=c60f3a72f52578b00cc7cb8551811cbc",
"original_total_additional_fees_set": null,
"original_total_duties_set": null,
"payment_gateway_names": [
"bogus"
],
"phone": null,
"po_number": null,
"presentment_currency": "INR",
"processed_at": "2023-09-22T08:14:43-04:00",
"reference": "6925f7d584e825b7f3fdbf5de7b3a5e1",
"referring_site": "",
"source_identifier": "6925f7d584e825b7f3fdbf5de7b3a5e1",
"source_name": "web",
"source_url": null,
"subtotal_price": "30.00",
"subtotal_price_set": {
"shop_money": {
"amount": "30.00",
"currency_code": "INR"
},
"presentment_money": {
"amount": "30.00",
"currency_code": "INR"
}
},
"tags": "",
"tax_exempt": false,
"tax_lines": [],
"taxes_included": false,
"test": true,
"token": "24a0946393b4889192c0d7056751e889",
"total_discounts": "0.00",
"total_discounts_set": {
"shop_money": {
"amount": "0.00",
"currency_code": "INR"
},
"presentment_money": {
"amount": "0.00",
"currency_code": "INR"
}
},
"total_line_items_price": "30.00",
"total_line_items_price_set": {
"shop_money": {
"amount": "30.00",
"currency_code": "INR"
},
"presentment_money": {
"amount": "30.00",
"currency_code": "INR"
}
},
"total_outstanding": "0.00",
"total_price": "30.00",
"total_price_set": {
"shop_money": {
"amount": "30.00",
"currency_code": "INR"
},
"presentment_money": {
"amount": "30.00",
"currency_code": "INR"
}
},
"total_shipping_price_set": {
"shop_money": {
"amount": "0.00",
"currency_code": "INR"
},
"presentment_money": {
"amount": "0.00",
"currency_code": "INR"
}
},
"total_tax": "0.00",
"total_tax_set": {
"shop_money": {
"amount": "0.00",
"currency_code": "INR"
},
"presentment_money": {
"amount": "0.00",
"currency_code": "INR"
}
},
"total_tip_received": "0.00",
"total_weight": 0,
"updated_at": "2023-09-22T08:14:47-04:00",
"user_id": null,
"billing_address": {
"first_name": null,
"address1": "Chennai",
"phone": "90909 09090",
"city": "Chennai",
"zip": "600012",
"province": "Tamil Nadu",
"country": "India",
"last_name": "Baid",
"address2": "Chennai",
"company": null,
"latitude": 13.098633,
"longitude": 80.2596083,
"name": "Baid",
"country_code": "IN",
"province_code": "TN"
},
"customer": {
"id": 6989864763541,
"email": "tom@gmail.com",
"accepts_marketing": false,
"created_at": "2023-09-22T08:14:44-04:00",
"updated_at": "2023-09-22T08:14:46-04:00",
"first_name": null,
"last_name": "Baid",
"state": "disabled",
"note": null,
"verified_email": true,
"multipass_identifier": null,
"tax_exempt": false,
"phone": null,
"email_marketing_consent": {
"state": "not_subscribed",
"opt_in_level": "single_opt_in",
"consent_updated_at": null
},
"sms_marketing_consent": null,
"tags": "",
"currency": "INR",
"accepts_marketing_updated_at": "2023-09-22T08:14:44-04:00",
"marketing_opt_in_level": null,
"tax_exemptions": [],
"admin_graphql_api_id": "gid://shopify/Customer/6989864763541",
"default_address": {
"id": 8320474546325,
"customer_id": 6989864763541,
"first_name": null,
"last_name": "Baid",
"company": null,
"address1": "Chennai",
"address2": "Chennai",
"city": "Chennai",
"province": "Tamil Nadu",
"country": "India",
"zip": "600012",
"phone": "90909 09090",
"name": "Baid",
"province_code": "TN",
"country_code": "IN",
"country_name": "India",
"default": true
}
},
"discount_applications": [],
"fulfillments": [],
"line_items": [
{
"id": 12623712354453,
"admin_graphql_api_id": "gid://shopify/LineItem/12623712354453",
"fulfillable_quantity": 1,
"fulfillment_service": "manual",
"fulfillment_status": null,
"gift_card": false,
"grams": 0,
"name": "Adania Pant - Black",
"price": "30.00",
"price_set": {
"shop_money": {
"amount": "30.00",
"currency_code": "INR"
},
"presentment_money": {
"amount": "30.00",
"currency_code": "INR"
}
},
"product_exists": true,
"product_id": 7907558064277,
"properties": [],
"quantity": 1,
"requires_shipping": true,
"sku": "",
"taxable": true,
"title": "Adania Pant",
"total_discount": "0.00",
"total_discount_set": {
"shop_money": {
"amount": "0.00",
"currency_code": "INR"
},
"presentment_money": {
"amount": "0.00",
"currency_code": "INR"
}
},
"variant_id": 43453026762901,
"variant_inventory_management": "shopify",
"variant_title": "Black",
"vendor": "twewr",
"tax_lines": [],
"duties": [],
"discount_allocations": []
}
],
"payment_terms": null,
"refunds": [],
"shipping_address": {
"first_name": null,
"address1": "Chennai",
"phone": "90909 09090",
"city": "Chennai",
"zip": "600012",
"province": "Tamil Nadu",
"country": "India",
"last_name": "Baid",
"address2": "Chennai",
"company": null,
"latitude": 13.098633,
"longitude": 80.2596083,
"name": "Baid",
"country_code": "IN",
"province_code": "TN"
},
"shipping_lines": [
{
"id": 4303065809045,
"carrier_identifier": "650f1a14fa979ec5c74d063e968411d4",
"code": "Standard",
"discounted_price": "0.00",
"discounted_price_set": {
"shop_money": {
"amount": "0.00",
"currency_code": "INR"
},
"presentment_money": {
"amount": "0.00",
"currency_code": "INR"
}
},
"phone": null,
"price": "0.00",
"price_set": {
"shop_money": {
"amount": "0.00",
"currency_code": "INR"
},
"presentment_money": {
"amount": "0.00",
"currency_code": "INR"
}
},
"requested_fulfillment_service_id": null,
"source": "shopify",
"title": "Standard",
"tax_lines": [],
"discount_allocations": []
}
]
}
```
```js
{
"id": 820982911946154500,
"admin_graphql_api_id": "gid://shopify/Order/820982911946154508",
"app_id": null,
"browser_ip": null,
"buyer_accepts_marketing": true,
"cancel_reason": "customer",
"cancelled_at": "2021-12-31T19:00:00-05:00",
"cart_token": null,
"checkout_id": null,
"checkout_token": null,
"closed_at": null,
"confirmed": false,
"contact_email": "jon@example.com",
"created_at": "2021-12-31T19:00:00-05:00",
"currency": "USD",
"current_subtotal_price": "398.00",
"current_subtotal_price_set": {
"shop_money": {
"amount": "398.00",
"currency_code": "USD"
},
"presentment_money": {
"amount": "398.00",
"currency_code": "USD"
}
},
"current_total_discounts": "0.00",
"current_total_discounts_set": {
"shop_money": {
"amount": "0.00",
"currency_code": "USD"
},
"presentment_money": {
"amount": "0.00",
"currency_code": "USD"
}
},
"current_total_duties_set": null,
"current_total_price": "398.00",
"current_total_price_set": {
"shop_money": {
"amount": "398.00",
"currency_code": "USD"
},
"presentment_money": {
"amount": "398.00",
"currency_code": "USD"
}
},
"current_total_tax": "0.00",
"current_total_tax_set": {
"shop_money": {
"amount": "0.00",
"currency_code": "USD"
},
"presentment_money": {
"amount": "0.00",
"currency_code": "USD"
}
},
"customer_locale": "en",
"device_id": null,
"discount_codes": [],
"email": "jon@example.com",
"estimated_taxes": false,
"financial_status": "voided",
"fulfillment_status": "pending",
"gateway": null,
"landing_site": null,
"landing_site_ref": null,
"location_id": null,
"merchant_of_record_app_id": null,
"name": "#9999",
"note": null,
"note_attributes": [],
"number": 234,
"order_number": 1234,
"order_status_url": "https://jsmith.myshopify.com/548380009/orders/123456abcd/authenticate?key=abcdefg",
"original_total_duties_set": null,
"payment_gateway_names": [
"visa",
"bogus"
],
"phone": null,
"presentment_currency": "USD",
"processed_at": null,
"processing_method": "",
"reference": null,
"referring_site": null,
"source_identifier": null,
"source_name": "web",
"source_url": null,
"subtotal_price": "388.00",
"subtotal_price_set": {
"shop_money": {
"amount": "388.00",
"currency_code": "USD"
},
"presentment_money": {
"amount": "388.00",
"currency_code": "USD"
}
},
"tags": "",
"tax_lines": [],
"taxes_included": false,
"test": true,
"token": "123456abcd",
"total_discounts": "20.00",
"total_discounts_set": {
"shop_money": {
"amount": "20.00",
"currency_code": "USD"
},
"presentment_money": {
"amount": "20.00",
"currency_code": "USD"
}
},
"total_line_items_price": "398.00",
"total_line_items_price_set": {
"shop_money": {
"amount": "398.00",
"currency_code": "USD"
},
"presentment_money": {
"amount": "398.00",
"currency_code": "USD"
}
},
"total_outstanding": "398.00",
"total_price": "388.00",
"total_price_set": {
"shop_money": {
"amount": "388.00",
"currency_code": "USD"
},
"presentment_money": {
"amount": "388.00",
"currency_code": "USD"
}
},
"total_shipping_price_set": {
"shop_money": {
"amount": "10.00",
"currency_code": "USD"
},
"presentment_money": {
"amount": "10.00",
"currency_code": "USD"
}
},
"total_tax": "0.00",
"total_tax_set": {
"shop_money": {
"amount": "0.00",
"currency_code": "USD"
},
"presentment_money": {
"amount": "0.00",
"currency_code": "USD"
}
},
"total_tip_received": "0.00",
"total_weight": 0,
"updated_at": "2021-12-31T19:00:00-05:00",
"user_id": null,
"billing_address": {
"first_name": "Steve",
"address1": "123 Shipping Street",
"phone": "555-555-SHIP",
"city": "Shippington",
"zip": "40003",
"province": "Kentucky",
"country": "United States",
"last_name": "Shipper",
"address2": null,
"company": "Shipping Company",
"latitude": null,
"longitude": null,
"name": "Steve Shipper",
"country_code": "US",
"province_code": "KY"
},
"customer": {
"id": 115310627314723950,
"email": "john@example.com",
"accepts_marketing": false,
"created_at": null,
"updated_at": null,
"first_name": "John",
"last_name": "Smith",
"state": "disabled",
"note": null,
"verified_email": true,
"multipass_identifier": null,
"tax_exempt": false,
"phone": null,
"email_marketing_consent": {
"state": "not_subscribed",
"opt_in_level": null,
"consent_updated_at": null
},
"sms_marketing_consent": null,
"tags": "",
"currency": "USD",
"accepts_marketing_updated_at": null,
"marketing_opt_in_level": null,
"tax_exemptions": [],
"admin_graphql_api_id": "gid://shopify/Customer/115310627314723954",
"default_address": {
"id": 715243470612851200,
"customer_id": 115310627314723950,
"first_name": null,
"last_name": null,
"company": null,
"address1": "123 Elm St.",
"address2": null,
"city": "Ottawa",
"province": "Ontario",
"country": "Canada",
"zip": "K2H7A8",
"phone": "123-123-1234",
"name": "",
"province_code": "ON",
"country_code": "CA",
"country_name": "Canada",
"default": true
}
},
"discount_applications": [],
"fulfillments": [],
"line_items": [
{
"id": 866550311766439000,
"admin_graphql_api_id": "gid://shopify/LineItem/866550311766439020",
"fulfillable_quantity": 1,
"fulfillment_service": "manual",
"fulfillment_status": null,
"gift_card": false,
"grams": 567,
"name": "IPod Nano - 8GB",
"price": "199.00",
"price_set": {
"shop_money": {
"amount": "199.00",
"currency_code": "USD"
},
"presentment_money": {
"amount": "199.00",
"currency_code": "USD"
}
},
"product_exists": true,
"product_id": 632910392,
"properties": [],
"quantity": 1,
"requires_shipping": true,
"sku": "IPOD2008PINK",
"taxable": true,
"title": "IPod Nano - 8GB",
"total_discount": "0.00",
"total_discount_set": {
"shop_money": {
"amount": "0.00",
"currency_code": "USD"
},
"presentment_money": {
"amount": "0.00",
"currency_code": "USD"
}
},
"variant_id": 808950810,
"variant_inventory_management": "shopify",
"variant_title": null,
"vendor": null,
"tax_lines": [],
"duties": [],
"discount_allocations": []
},
{
"id": 141249953214522980,
"admin_graphql_api_id": "gid://shopify/LineItem/141249953214522974",
"fulfillable_quantity": 1,
"fulfillment_service": "manual",
"fulfillment_status": null,
"gift_card": false,
"grams": 567,
"name": "IPod Nano - 8GB",
"price": "199.00",
"price_set": {
"shop_money": {
"amount": "199.00",
"currency_code": "USD"
},
"presentment_money": {
"amount": "199.00",
"currency_code": "USD"
}
},
"product_exists": true,
"product_id": 632910392,
"properties": [],
"quantity": 1,
"requires_shipping": true,
"sku": "IPOD2008PINK",
"taxable": true,
"title": "IPod Nano - 8GB",
"total_discount": "0.00",
"total_discount_set": {
"shop_money": {
"amount": "0.00",
"currency_code": "USD"
},
"presentment_money": {
"amount": "0.00",
"currency_code": "USD"
}
},
"variant_id": 808950810,
"variant_inventory_management": "shopify",
"variant_title": null,
"vendor": null,
"tax_lines": [],
"duties": [],
"discount_allocations": []
}
],
"payment_details": {
"credit_card_bin": null,
"avs_result_code": null,
"cvv_result_code": null,
"credit_card_number": "•••• •••• •••• 1234",
"credit_card_company": "Visa",
"buyer_action_info": null,
"credit_card_name": null,
"credit_card_wallet": null,
"credit_card_expiration_month": null,
"credit_card_expiration_year": null
},
"payment_terms": null,
"refunds": [],
"shipping_address": {
"first_name": "Steve",
"address1": "123 Shipping Street",
"phone": "555-555-SHIP",
"city": "Shippington",
"zip": "40003",
"province": "Kentucky",
"country": "United States",
"last_name": "Shipper",
"address2": null,
"company": "Shipping Company",
"latitude": null,
"longitude": null,
"name": "Steve Shipper",
"country_code": "US",
"province_code": "KY"
},
"shipping_lines": [
{
"id": 271878346596884000,
"carrier_identifier": null,
"code": null,
"delivery_category": null,
"discounted_price": "10.00",
"discounted_price_set": {
"shop_money": {
"amount": "10.00",
"currency_code": "USD"
},
"presentment_money": {
"amount": "10.00",
"currency_code": "USD"
}
},
"phone": null,
"price": "10.00",
"price_set": {
"shop_money": {
"amount": "10.00",
"currency_code": "USD"
},
"presentment_money": {
"amount": "10.00",
"currency_code": "USD"
}
},
"requested_fulfillment_service_id": null,
"source": "shopify",
"title": "Generic Shipping",
"tax_lines": [],
"discount_allocations": []
}
]
}
```
```js
{
"userId":"6989864763541",
"email":"andrew@gmail.com",
"fistName": "andrew",
"lastName":"farak",
"phone": "9909889090",
"coutry": "IN",
"sessionId":"ym_1695384819786_bzldxorc5q",
"source":"shopify"
}
```
```json
{
"id": 3547267221,
"admin_graphql_api_id": "gid://shopify/Return/3547267221",
"status": "requested",
"order": {
"id": 5196695273621,
"admin_graphql_api_id": "gid://shopify/Order/5196695273621"
},
"total_return_line_items": 1,
"name": "#1106-R2",
"return_line_items": [
{
"id": 6200524949,
"admin_graphql_api_id": "gid://shopify/ReturnLineItem/6200524949",
"fulfillment_line_item": {
"id": 10736341352597,
"admin_graphql_api_id": "gid://shopify/FulfillmentLineItem/10736341352597",
"line_item": {
"id": 12695210000533,
"admin_graphql_api_id": "gid://shopify/LineItem/12695210000533"
}
},
"quantity": 1,
"return_reason": "unwanted",
"return_reason_note": "",
"customer_note": null
}
],
"customer": {
"id": 7029431102139,
"email": "andrew@gmail.com",
"accepts_marketing": false,
"created_at": "2023-10-18T07:18:03-04:00",
"updated_at": "2023-10-19T06:19:34-04:00",
"first_name": "Andrew",
"last_name": "B",
"state": "disabled",
"note": null,
"verified_email": true,
"multipass_identifier": null,
"tax_exempt": false,
"phone": null,
"email_marketing_consent": {
"state": "not_subscribed",
"opt_in_level": "single_opt_in",
"consent_updated_at": null
},
"sms_marketing_consent": null,
"tags": "",
"currency": "INR",
"accepts_marketing_updated_at": "2023-10-18T07:18:03-04:00",
"marketing_opt_in_level": null,
"tax_exemptions": [],
"admin_graphql_api_id": "gid://shopify/Customer/7029431102139",
"default_address": {
"id": 836448003234781,
"customer_id": 7029431102139,
"first_name": "Andrew",
"address1": "Kerala",
"address2": null,
"city": "Manglore",
"province": "Kerala",
"country": "India",
"zip": "574241",
"phone": "09008692935",
"province_code": "KL",
"country_code": "IN",
"country_name": "India",
"default": true
}
}
}
```
### Run campaigns based on Shopify events
You can initiate Flow campaigns based on Shopify events that you have enabled in Yellow.ai.
In [Flow campaigns](https://docs.yellow.ai/docs/platform_concepts/engagement/flows_campaign), choose **Condition** as *Has done event check* and in **Campaign triggers when user**, choose the event that you want to use to trigger campaigns.
Here are some examples:
In an online store on Shopify, you notice that some customers abandon their shopping carts during the checkout process. To recover those potential sales, set up a Flow campaign to automatically send reminders to users who have abandoned their shopping carts on your Shopify store.
**Entry trigger**: `shopifyCartCreate` event
**Exception to trigger notification**: `ShopifyCheckoutCreated` event
**Flow configuration**:
1. **Trigger the flow**: Initiate the campaign when a user adds items to their cart, identify it using the `shopifyCartCreate` event.
2. **Wait condition**: Check if the user has completed the purchase by waiting for the `ShopifyCheckoutCreated` event. Set time delay, say 10 min. If no `ShopifyCheckoutCreated` event is detected within 10 min, proceed to the next step.
3. **Send abandonment reminder**: If the user has not completed the purchase within the specified time, send a WhatsApp notification. Here is a sample message:
- *Sample Notification Message:* "Hello [User's Name], we noticed you left some wonderful items in your cart. 🛒 Don't miss out on these great finds! Tap here to complete your purchase: [Checkout Link]. Thank you for choosing our store!"
When a new customer registers in your Shopify store, initiate a series of welcome emails, introducing them to your products and offering exclusive discounts on their first purchase.
* **Event**: ShopifyNewCustomer
* **Wait time**: Immediately
When an order is successfully placed (shopifyNewOrder event), send an order confirmation campaign. This includes order details, expected delivery date, and a thank-you message.
For customers who cancelled an order on Shopify store, trigger a well-crafted campaign aimed at enticing customers to initiate a new transaction. The campaign is designed to re-engage customers who experienced an order cancellation and guide them toward completing a new purchase.
* **Event**: ShopifyOrderCancelled
* **Wait time**: 24 hours
* **Sample message**:
```
Subject: Exclusive Offer for Your Next Purchase 🛒
Message:
Dear [Customer's Name],
We noticed that your recent order was canceled, and we're here to make it up to you with an exclusive offer.
To show our appreciation for your continued support, we're pleased to offer you a special 20% discount on your next purchase. Use code: REORDER20 at checkout to enjoy your savings.
We've also handpicked some fantastic product recommendations based on your previous preferences, which we think you'll love:
Recommended Products:
[Product 1]
[Product 2]
[Product 3]
Explore these selections and easily add them to your cart with just a click.
[Shop Now]
```
:::note
You will see only events that you have enabled for the bot. For more details, [see how to activate events](#activate-shopify-events-you-wish-to-use-in-automation).
:::
To know more about Flow campaigns, click [here](https://docs.yellow.ai/docs/platform_concepts/engagement/flows_campaign).
***
## 4. Access Shopify data in bot conversations
Once the integration is set up, Shopify events start flowing to Yellow.ai. These events serve as triggers for bot flows, enabling the creation of personalized conversations, running effective campaigns, storing customer data in User360,personalized responses, data enrichment, and the creation of efficient workflows.
### Supported Shopify events you can use in Automation
The following table provides a comprehensive list of Shopify events along with their descriptions and sample use cases.
| Event | Description | Sample use cases |
|--------|----------------|----------------------|
| shopifyNewOrder | A new order is created in the Shopify store. | - Trigger order confirmation emails- Update inventory when a new order is created in your Shopify store. |
| shopifyNewProduct | A new product has been added to the Shopify store. | - Update the product catalog- Create product listings- Send WhatsApp notifications when a new product is added to your Shopify store. |
| shopifyOrderCancelled | An order is cancelled. | - Handle order cancellations- Update inventory levels- Refund payments- Notify customers when their orders are canceled. |
| shopifyOrderFulfilled | An order was fulfilled or completed. | Update shipping information- Send shipping notifications to customers- Update order status when an order is fulfilled or completed. |
| shopifyOrderPaid | Payment made for an order. | - Send payment receipts- Update financial records when a payment is made for an order. |
| shopifyRefundCreated | A refund was created for an order. | - Update financial records- Notify customers about their refunds- Adjust inventory levels when a refund is issued for an order. |
| shopifyNewCustomer | A new customer is registered. | - Add the customer to User 360- Send welcome emails- Track customer acquisition when a new customer registers in your Shopify store. |
| shopifyCustomerUpdate | A customer’s profile details have been updated. | - Keep your customer database up to date- Send profile change notifications when a customer's profile details are updated. |
| shopifyCheckoutCreated| Order checkout is initiated in Shopify. | - Track order progress when an order checkout is initiated in your Shopify store. |
| shopifyOrdersUpdated | Shopify order is updated. | - Monitor order changes- Adjust inventory- Notify the customer about order updates to handle order updates in the Shopify store. |
### Events enabled by default in Studio
Once your integration is set up, the following events are sent to bot directly are available by default with this integration.
* shopifyRefundCreated
* shopifyNewProduct
* shopifyOrderPaid
:::note
The availability of events within the integration depends on the scopes you have enabled when generating the API token.
:::
### Activate Shopify events you wish to use in Automation
Apart from the events mentioned in the previous section, you can enable other events that you want to make use in Automation. For a list of events supported in Automation, see [here](#supported-shopify-events-you-can-use-in-automation).
To enable events:
1. Go to **Automation** > **Event** > **Integrations**. You will see all the events related to Shopify with the prefix `shopify`.
2. Navigate to the event that you want to enable and click on the more options icon > **Activate**.
3. Once you enable required shopify events, you can use these Shopify events to:
* [Trigger bot flows via events](https://docs.yellow.ai/docs/platform_concepts/studio/build/Flows/configureflow#trigger-flow-using-event)
* [Initiate flow campaigns based on events](https://docs.yellow.ai/docs/platform_concepts/engagement/flows_campaign#user-events)
* [Store user variables that come from user events into user properties](https://docs.yellow.ai/docs/platform_concepts/engagement/cdp/user_data/store_conv_data#store-user-properties-from-bot-conversations)
:::note
**Error: Webhook is failing**:
* Ensure you have activated the respective event as mentioned above. If your webhook fails more than twice, it will be removed and your application will not receive any notifications.
:::
### Fetch Shopify data in bot conversations
To make use of Shopify events in bot flows:
1. Go to your bot in **Automation** and navigate to the flow where you want to use a Shopify event.
3. Navigate to the Integration node - **Node** > **Integration** > **Shopify Shop**.
4. Choose your **Account name**
5. Select the respective **Action** that you need to perform.
5. In **Var** pass the parameter variable that contains the required information in the format `variables.objVariableName.key`.
6. Use **Show sample response** to see all the details (in the JSON format) that the function can retrieve.
7. To store the response, use **Store the response in** a [variable](https://docs.yellow.ai/docs/platform_concepts/studio/build/bot-variables).
8. You can decide which info to display to the user. Use the **Function** node to customise that information in the **Code** tab.
For example, in the previous screenshot, order details are stored in the variable `order_details`. You can access this data using order_details.order.name.
### Shopify action nodes with Sample payloads
You can see all the Shopify action nodes in **Integration** > **Shopify** node (Refer to the previous section for more details).
The following are some limitations with these action nodes:
1. **Data Fetch Limitation**: You can retrieve a maximum of 50 records (products/orders/collections etc.) in a single query or request.
2. **Object Size Restriction**: The response object size is limited to 90KB. The data you send or receive should not exceed this limit.
3. **Product Display Limitation**: When displaying product details, you can showcase up to 8 carousel images. This limitation is due to the inability to use a "Next" option to view additional products in subsequent lists.
These points highlight the specific constraints and limitations that users or developers should be aware of when working with this system or application.
This function retrieves order details using the provided order ID.
Parameter | Datatype | Example
-------- | --------- | -------
order_id | Number | 632910392
Here is a sample response schema:
```json
{
"order": {
"id": 450789469,
"cancel_reason": null,
"cancelled_at": null,
"confirmed": true,
"email": "bob.norman@example.com",
"financial_status": "partially_refunded",
"fulfillment_status": null,
"name": "#1001"
}
}
```
This function retrieves order details using the provided order number.
Parameter | Datatype | Sample value
--------- | -------- | ------------
order_number | Number | 1001
```json
{
"orders": [
{
"id": 450789469,
"cancel_reason": null,
"cancelled_at": null,
"confirmed": true,
"email": "bob.norman@hostmail.com",
"financial_status": "partially_refunded",
"fulfillment_status": null,
"name": "#1001"
}
]
}
```
This function retrieves the details of a specific product using the `product_id`.
Parameter | Datatype | Example
--------- | -------- | -------
product_id | Number | 632910392
```json
{
"product": {
"id": 632910392,
"title": "IPod Nano - 8GB",
"product_type": "Cult Products",
"variants": [
{}]
}
}
```
This function retrieves the list of all the variants of a product using the `product_id`.
Parameter | Datatype | Example
-------- | --------- | --------
product_id | Number | 632910392
```json
{
"variants": [
{
"id": 39072856,
"product_id": 632910392,
"title": "Green",
"price": "199.00",
"sku": "IPOD2008GREEN"
}
]
}
```
This function retrieves all the products under a specific collection from shopify using the `collection_id`.
Parameter | Datatype | Example
--------- | -------- | -------
collection_id | String | 76854321
Here is a sample response schema:
```json
{
"products": [
{
"id": 632910392,
"title": "IPod Nano - 8GB",
"variants": [
{
"id": 808950810,
"product_id": 632910392,
"title": "Pink",
"price": "199.00"
}
]
}
]
}
```
This function fetches products by `title`.
Parameter | Datatype | Example
-------- | -------- | -------
title | String | Ipad Nano
```json
{
"products": [
{
"id": 632910392,
"title": "IPod Nano - 8GB",
"variants": [
{
"id": 808950810,
"product_id": 632910392,
"title": "Pink",
"price": "199.00"
}
]
}
]
}
```
This function retrieves all the orders of a customer using the `customer_id`.
Parameter | Datatype | Sample value
-------- | --------- | -----------
customer_id | String | 207119551
```json
{
"orders": [
{
"id": 450789469,
"email": "bob.norman@hostmail.com",
"created_at": "2008-01-10T11:00:00-05:00",
"updated_at": "2008-01-10T11:00:00-05:00",
"total_price": "598.94",
"financial_status": "partially_refunded"
}
]
}
```
This function fetches all the available collections from shopify using the `collection_id`.
Parameter | Datatype | Sample value
--------- | -------- | ------------
collection_id | Number | 482865238
```json
{
"collection_listings": [
{
"collection_id": 482865238,
"updated_at": "2022-02-03T16:53:36-05:00",
"body_html": "The best selling ipod ever",
"default_product_image": null,
"handle": "smart-ipods",
"image": {
"created_at": "2022-02-03T16:53:36-05:00",
"src": "https://cdn.shopify.com/s/files/1/0005/4838/0009/collections/ipod_nano_8gb.jpg?v=1643925216"
},
"title": "Smart iPods",
"sort_order": "manual",
"published_at": "2017-08-31T20:00:00-04:00"
}
]
}
```
### Map shopify data to user properties
You can add/update user properties with Shopify data through bot conversations by mapping them to user properties. This enables you to create highly personalized and engaging interactions with your users.
For detailed instructions, see [Add user variables that come from user events into user properties](https://docs.yellow.ai/docs/platform_concepts/engagement/cdp/user_data/store_conv_data#store-user-properties-from-bot-conversations).
You can create personalized conversations using stored properties, [know how](https://docs.yellow.ai/docs/platform_concepts/engagement/cdp/user_data/personalise_conversations).
---
***
## 5. Import Shopify bot from Marketplace template
Importing a Shopify bot template into your Yellow.ai account is a straightforward process that streamlines the integration of Yellow.ai with your Shopify store. This template provides pre-configured floes and actions designed to enhance your e-commerce operations. This includes flows such as Browse products, Get order details, authenticate user via OTP, show customer details, connect to support, and raise ticket.
To import the Shopify shop template in your bot:
1. Navigate to the **Marketplace** and search for Shopify. You will see Shopify E-commerce with Shopify integration.
2. Select the template and click **+Use Template**.
The template will start importing. Wait until the import is complete.
5. Open the **Flows** dropdown to see the new flows added to the bot.
---
## 6. Troubleshooting
**Error: Your webhook is failing**
Ensure you have enabled Shopify's event in **Event Hub**. If your webhook fails more than twice, it will be removed and your application will not receive any notifications.
---
## 7. Disconnect Shopify integration
To remove this integration from your bot:
1. On the bot configuration page, go to **Integrations**.
2. Search for **Shopify shop** > **Disconnect**.
---
### Important References
1. [Shopify Custom Apps](https://help.shopify.com/en/manual/apps/custom-apps)
2. [Configuring Storefront data for getAllCollections integration node](https://community.shopify.com/c/shopify-apis-and-sdks/404-error-from-get-admin-collection-listings-json-for-one-store/m-p/367034/highlight/true#M19606)
---
## Stripe Payment integration
Yellow.ai Integration with Stripe Payment Gateway allows the AI agent to generate Stripe payment links and view a specific payment status.
## Connecting Stripe payment with yellow.ai
### Get Secret key from your Stripe app
* Go to the **Stripe** dashboard > **Developer** > **API Keys** > Copy the **Secret key**.
### Connect Stripe with yellow.ai
In a two-tier environment, you can connect an integration app in the Development environment. In a three-tier environment, you can connect the integration app either in Staging or Sandbox. All connected integrations are available in the live environment.
To connect your Airpay account with Yellow.ai, follow these steps:
1. Navigate to the Development/Staging environment and go to **Extensions** > **Integrations** > **Payment** > **Stripe**.
2. In **Give account name**, enter a unique name for the integration. You can use only lowercase alphanumeric characters and underscores (_).
3. Enter the **Key secret** that you copied using the previous sections.
4. Click **Connect**.
5. To add another account, click **+ Add account** and proceed with the previous steps. You can add a maximum of 15 accounts.
### Configure webhook URL in Stripe dashboard.
The webhook URL serves as a callback endpoint where Stripe can send notifications or updates regarding payment events, enabling your application to respond accordingly.
1. Copy the webhook URL from Stripe integration card.
2. Go to the Stripe **Dashboard** > **Developers** > **Webhooks** > **Add endpoint**.
3. Enter the webhook URL in **Endpoint** field.
4. Select **checkout.session.completed** event in the select events to listen field.
## Receiving Stripe payment status event in your AI agent
Enable the following event under Events section:
1. In Development/Staging environment, go to **Automation** > **Event** > **Custom events**.
2. Navigate to the `stripe-payment-gateway` event, click on the more options icon and select **Activate**.
Event | Description
----- | -----------
Stripe Payment Status | In case of payments/refunds the status can be checked with these details.
## Generate Stripe payment link through AI agent conversation
Once the Stripe account is connected, you can generate the payment link directly in AI agent conversations.
1. Go to Development/Staging environment and navigate to **Automation** > **Build** > Select the flow where you want to add the Generate payment link node.
2. Click **Add node** > **Integrations** > **Stripe payment gateway**.
Option | Datatype | Description
------ | -------- | -----------
Amount* | number | Choose a variable that contains the amount to be used in the payment link.
Currency* | String | Choose a variable that contains the currency to be used in the payment link
Description* | String | Choose a variable that contains the description to be included in the payment link.
Custom metadata* | Object | Choose a variable that contains the custom metadata to be included in the payment link.
Product image* | string | Choose a variable that contains the URL of the product image to be included in the payment link.
Product name* | String | Choose a variable that contains the name of the product to be included in the payment link.
After Completion type | String | The action to be taken after the payment is completed. You can choose to redirect the user to a specific URL or display a custom message.
URL or Custom Message | String | For Redirect URL: Enter the URL to which the user should be redirected. For Show Custom Message: Enter the custom message that you want to display to the user.
Parse API response | - | Choose the function that you want to use to parse and handle the response received from the API after completing the payment. Parsing the API response allows the AI agent to extract relevant information and take appropriate actions based on the response.
# Reference
For more information about action nodes you use here, refer this [doc](https://stripe.com/docs/payments/payment-links)
---
## SuccessFactors Integration
## Configuration Requirements
### API Endpoint
```
https://[API-Server]/odata/v2/[Entity]/$metadata
```
### Authorization
```
Basic Base64(username@companyId:password)
```
### Supported Filters
```
eq, in, and, or, ge, le, not, like, etc.
$filter=username eq 'abc@abc.com' and location in 'In','Eu'
```
---
## Employee Profile
### Active Employee
```bash
curl --location --request GET 'https://api44.sapsf.com/odata/v2/User?$filter=username%20eq%20%27abc@yellowmessenger.com%27&$format=json' \
--header 'Authorization: Basic XXXXX'
```
### Deactivate / Ex-Employee
```bash
curl --location --request GET 'https://api44.sapsf.com/odata/v2/User?$filter=username%20eq%20%27abc@yellowmessenger.com%27%20and%20status%20eq%20%27f%27&$format=json&$select=defaultFullName,userId,jobCode,email,hireDate' \
--header 'Authorization: Basic XXXXX'
```
### Employment Termination Info
```bash
curl --location --request GET 'https://api44.sapsf.com/odata/v2/EmpEmploymentTermination?$filter=userId%20eq%20300&$format=json' \
--header 'Authorization: Basic XXXXX'
```
---
## Leave Management
### SuccessFactors Leave Entities
| Entity | Description |
|------------------|-----------------------------------------------------------------------------|
| Time Account Type | Rules to accrue balance for each leave type |
| Time Type | Types of leave (e.g., Annual Leave, Sick Leave) |
| Time Profile | Leave types applicable to employees |
| Time Account | Holds the obtained leave balance |
### Managing Time Off Entities
1. Log in to SuccessFactors with admin access.
2. Search for **Manage Time Off Structure**.
3. Select desired entity from dropdown.
4. Select a record to update.
5. Take Action → Make Correction → Save.
### Adding a New Record
Use the right-side dropdown to select entity category and add a record.
### Assigning Time Profile to Employee
1. Search employee in the top search bar.
2. Go to Job Information → Edit.
3. Update time profile, work schedule, holiday calendar.
4. Save changes. A time account is auto-created.
### Sample Config
- **Time Profile**: Time off Test (`TIME_OFF_TEST`)
- **Time Types**:
- Sick Leave: `SICK_LEAVE`
- Annual Leave 2: `ANNUAL_LEAVE`
---
## Leave Balance Calculation
### Past Leaves (Response1)
```bash
curl --location --request GET 'https://api44.sapsf.com/odata/v2/EmpTimeAccountBalance?$filter=userId%20eq%20%27273%27%20and%20timeAccountType%20eq%20%27SICK_LEAVE%27&$format=json' \
--header 'Authorization: Basic XXXXX'
```
### Future Approved Leaves (Response2)
```bash
curl --location --request GET 'https://api44.sapsf.com/odata/v2/EmployeeTime?$filter=userId%20eq%20%27273%27%20and%20timeType%20eq%20%27ANNUAL_LEAVE%27%20and%20startDate%20ge%20datetime%272020-02-04T00:00:00%27%20and%20approvalStatus%20eq%20%27PENDING%27&$format=json&$select=deductionQuantity,approvalStatus,timeType,endDate,startDate,externalCode' \
--header 'Authorization: Basic XXXXX'
```
### Final Balance Formula
```text
finalBalance = Response1.balance - SUM(Response2[].deductionQuantity)
```
---
## Apply Leave
```bash
curl --location --request POST 'https://api44.sapsf.com/odata/v2/upsert?workflowConfirmed=true&$format=json' \
--header 'Authorization: Basic XXXXX' \
--header 'Content-Type: application/json' \
--data-raw '{
"__metadata": {
"uri": "https://api44.sapsf.com/odata/v2/EmployeeTime('273')"
},
"startDate": "{{todayDate}}",
"endDate": "/Date(1611792000000)/",
"externalCode": "TRY1234",
"approvalStatus": "PENDING",
"userIdNav": {
"__metadata": {
"uri": "https://api44.sapsf.com/odata/v2/User('273')",
"type": "SFOData.User"
}
},
"timeTypeNav": {
"__metadata": {
"uri": "https://api44.sapsf.com/odata/v2/TimeType('SICK_LEAVE')",
"type": "SFOData.TimeType"
}
}
}'
```
### Sample Responses
**Failure:**
```json
{
"d": [
{
"key": "EmployeeTime/externalCode=TRY1234",
"status": "ERROR",
"message": "Expected return date must be one day later than end date.",
"httpCode": 500
}
]
}
```
**Success:**
```json
{
"d": [
{
"key": "EmployeeTime/externalCode=TRY1234",
"status": "OK",
"editStatus": "UPSERTED",
"httpCode": 200
}
]
}
```
---
## Verification in Portal
- **User Profile:** Navigate to _User Profile → Actions → Manage leave of absence._
- **Manage Data:** Go to _Manage Time Off Structures → Employee Time → [externalCode]_
## References
1. SAP API Guide : https://help.sap.com/viewer/d599f15995d348a1b45ba5603e2aba9b/2011/en-US
2. https://blogs.sap.com/2015/10/16/ec-time-off-for-on-time-hr-management/
---
## Talisma Livechat Integration
## 1. Configuration
- Inside your project, navigate to the Configuration tab and click **Integrations**. Search for **Talisma live chat**.
- Click **Connect**. Enter **Talisma Api Base Url** and **Agent Timeout** value.
If you have multiple accounts, follow the above mentioned steps to add each of them.
:::note
1. Enter a unique name for each account to easily identify them within the yellow.ai platform. It is recommended to use a name that aligns with its purpose for better usability.
2. You can add a maximum of 15 accounts.
3. In a two-tier environment, such as bots with only Development/Live environments, you can add account names only in the development mode. Once added and flows have been built, in the Live mode, you can only choose the account names and not edit them.
4. In a three-tier environment, such as bots with Staging/Sandbox/Production modes, in Staging and Sandbox modes, you can add and edit new accounts. However, in Production, only the account details added in Staging will be available. You can only map in the production environment.
:::
## 2. Use Case
:::info
Use **Ticket-closed** in the **Raise Ticket node** to perform specific actions when a live chat closes, instead of using the **ticket-close** event.
:::
In this integration, you can use [raise ticket](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/raise-ticket) node to create a conversation with Talisma agent. Once the conversation is initiated the user can talk to the talisma agent.
After the conversation between them ends, the bot takes over the conversation with the user.
:::note
When multiple accounts are added, select the appropriate account for each node, allowing you to leverage the unique functionalities of each account for their intended purposes.
:::
**Support**
The text and attachments (image, file) is being supported from the user and agent's side.
---
**Reference**
---
## Twilio Verify
## Scope of Integration
Yellow.ai Integration with Twilio Verify allows you to seamlessly connect your Twilio Verify service with the yellow.ai platform. Any customer who has a Twilio account will be able to seamlessly connect their verify service with yellow.ai using basic auth with account SID, Auth Token and Verify Service SID. This connector will enable users to verify end user identity using OTP verification by means of SMS, call or email.
## Configuration
Configuring the integration with Twilio Verify is straightforward.
Follow the steps defined below to start integrating:
1. Navigate to Integrations Tab:
Inside your project, navigate to the Configuration tab and then click on the Integrations Tab. Search for Twilio Verify.
2. Connect your Twilio Verify account:
Enter the values for Account SID, Auth token and verify service SID to connect to your Twilio account.
Voila! And just like that, you are now connected with your Twilio account.
If you have multiple accounts, follow the above mentioned steps to add each of them.
:::note
1. Enter a unique name for each account to easily identify them within the yellow.ai platform. It is recommended to use a name that aligns with its purpose for better usability.
2. You can add a maximum of 15 accounts.
3. In a two-tier environment, such as bots with only Development/Live environments, you can add account names only in the development mode. Once added and flows have been built, in the Live mode, you can only choose the account names and not edit them.
4. In a three-tier environment, such as bots with Staging/Sandbox/Production modes, in Staging and Sandbox modes, you can add and edit new accounts. However, in Production, only the account details added in Staging will be available. You can only map in the production environment.
:::
## Use Case
Following are the use-cases which are currently accommodated in the Integration:
Simple Integration using credentials
To enable integration with Twilio verify, you need account SID, authentication token and verify service SID. You can get account SID, authentication token and verify service SID from twilio dashboard.
Take actions with Twilio Verify nodes
Using the Twilio Verify integration nodes, you can send and verify OTP to the end user. You can choose the action node corresponding to the channel (SMS, call and email) via which you want to send the OTP. After choosing the appropriate action node, you need to enter the receiver to whom you want to send OTP.
Then you need to ask the user for OTP to verify it. After that you need to create a Twilio Check Verification action node and provide values for receiver and OTP to verify if OTP provided by the user is correct. If it is correct, you’ll get “status”: “approved” in response object.
:::note
When multiple accounts are added, select the appropriate account for each node, allowing you to leverage the unique functionalities of each account for their intended purposes.
:::
# Reference
This integration will support the latest version releases, latest one being v2
API Documentation: [https://www.twilio.com/docs/verify](https://www.twilio.com/docs/verify)
---
## WebEngage
Yellow.ai integration with WebEngage allows you to seamlessly send WhatsApp campaigns to your customers. Any business user who has a WebEngage account can simply login to their WebEngage account, choose Yellow.ai as their WSP (WhatsApp Service Provider). Provide the API key to setup the configuration, upload the audience list and initiate the whatsapp campaign.
Yellow.ai uses its notification engine service to run the whatsapp campaign based on the events received from WebEngage. The notification delivery status report is sent to WebEngage by invoking their static REST endpoint.
In this article, you will learn how to integrate WebEngage on yellow cloud platform.
**Detailed workflow**
:::note
While using a bot of app.yellow.ai, navigate to the Data explorer section in the Growth Module, which will redirect you to the cloud.yellow.ai UI.
After that, you can move to the Integrations section and search for WebEngage to get the instructions.
:::
## 1. Configuration
Configuring the integration with WebEngage is straightforward. Follow the steps below to integrate WebEngage:
1. From the switcher, click on the **Integrations**.
2. Search for **WebEngage**.
3. Provide the **API key** from the description. Click **Connect** to see the list of instructions provided in the description card and then click **Update** to enable the integration.
4. If you have multiple accounts, follow the above mentioned steps to add each of them.
:::note
1. Enter a unique name for each account to easily identify them within the yellow.ai platform. It is recommended to use a name that aligns with its purpose for better usability.
2. You can add a maximum of 15 accounts.
3. In a two-tier environment, such as bots with only Development/Live environments, you can add account names only in the development mode. Once added and flows have been built, in the Live mode, you can only choose the account names and not edit them.
4. In a three-tier environment, such as bots with Staging/Sandbox/Production modes, in Staging and Sandbox modes, you can add and edit new accounts. However, in Production, only the account details added in Staging will be available. You can only map in the production environment.
:::
## 2. Use case
Following are the use-cases which are currently accommodated in the Integration:
:::note
When multiple accounts are added, select the appropriate account for each node, allowing you to leverage the unique functionalities of each account for their intended purposes.
:::
1. **Take actions with WebEngage nodes**: You can send the delivery status report of the notification sent by using the Delivery Report Action Nodes. There are two action nodes, one for India Region and the other for US Region. The selection of action nodes is conditional(based on the country code received from WebEngage’s end. If the country code is IN, the Delivery Report India Region action node needs to be used, else the US Region action node needs to be used).
2. **Receive events**: On sending the WhatsApp notification using yellow.ai’s notification engine service, an event is received stating the details of the delivery report.
---
## Custom Webhook integration
This custom webhook integration helps the bot to receive instant notifications about user actions, such as adding products to their cart or completing purchases.
Pre-built integrations may not suit all client setups. Implementing webhooks ensures seamless communication between our bot and both in-house and third-party systems, accommodating various client configurations. For example, clients utilizing third-party systems can still receive timely updates about user actions.
To configure a Webhook account, follow these steps:
1. In Development/Staging environment, go to **Extensions** > **Integrations** > **Tools & Utilities** > **Custom Webhook**. Alternatively, you can use the Search box to find a specific integration.
2. In **Give account name**, enter a unique name for the integration. You can use only lowercase alphanumeric characters and underscores (_).
3. Configure the other details based on the description provided in the following table.
Option | Description
------ | -----------
Provider | Either choose *Custom webhook* to add a new webhook account or select a preconfigured webhook that you want to use.
Domain name | Enter the domain for example
Webhook payload | The data format or structure of the payload sent via the webhook. Describe the content and format expected in the JSON payload.
Send event data to user | Toggle to *Yes* to send event data received via the webhook to the user. By default, this option is set to *No*. For example, show status of the payment. For audit or any other purposes, the bot developer should add logic based on the event to store event data.
Choose from default source? | Toggle to *Yes* to Specifies whether to select from a default source.
Authenticate key | Enter the auth key for authentication purposes.
Sender path | Specifies the path or endpoint from which the webhook sender transmits data. Choose the relevant parameter used in the webhook payload.
Source path | The path or endpoint from which the webhook source sends data. Describe the format or structure of the source path.
Other parameters | Map any additional parameters relevant to the webhook integration. For example, account name.
:::note
- We have preconfigured the most common custom webhooks and will continue to add more commonly used webhooks over time. Simply select the provider, and no further configurations are required.
- The following screenshot shows how the Webhook payload parameters appear in Sender path and Source path:
:::
4. Click **Connect**.
5. To add more accounts, click **+Add account** and repeat the above procedure.
6. Once an account is added, you can copy the webhook URL by clicking on the Webhook link.
:::note
- Once the account is added, you can copy the Webhook URL.
:::
## Enable Webhook events in Automation
Once integration is complete, to make use of events in the bot, users need to enable events.
1. Go to **Automation** > **Event** > **Integrations**.
2. Search for *Custom webhook*, click on more options and Activate the event. If there are multiple accounts, you need to activate for each account separately.
---
## Workday Integration Guide
Workday is a leading Human Capital and Financial Operations managing platform that offers centralized access to critical business data—employee records, payroll, financial transactions, supplier contracts, and more.
This guide helps you integrate Workday with the Yellow.ai platform to automate data exchange, improve operational efficiency, and support business decision-making. Whether you're looking to sync employee information, trigger workflows based on Workday events, or use Workday data to personalize interactions, this guide will walk you through setup and best practices.
## Connect Workday with Yellow.ai
To integrate Workday with the Yellow.ai platform, follow the steps below:
1. Switch to the Development/Staging environment and go to **Extensions** > **Integrations** > **HR** > **Workday**. Alternatively, you can use the Search box to quickly find the required integration.
2. In **Give account name**, enter a unique name for the integration. You can use only lowercase alphanumeric characters and underscores (_).
3. Configure the following fields required for integration and click **Connect**.
Below is a detailed list of required fields to connect your Workday integration, along with instructions on how to obtain each value.
| **Field** | **Description** | **How to Obtain** |
|--------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **API Base URL** * | The root URL for your Workday API environment. This varies based on your tenant and environment (e.g., production or sandbox).**Example:** `https://wd3-impl-services1.workday.com` | 1. Log in to your Workday account. 2. Search for and open the **View API Clients** report. 3. Locate the **Workday REST API Endpoint** — this is your base URL. |
| **Instance ID** * | A unique identifier for your Workday tenant. **Example:** If your Workday URL is `https://acme.workday.com`, then `acme` is your instance ID. | 1. Log in to Workday. 2. Look at the browser’s address bar — it typically follows the format `https://[instance_id].workday.com`. |
| **Client ID** * | A unique identifier for your registered application in Workday. Used during OAuth to identify your integration. | 1. In Workday, search for **Register API Client**. 2. Fill in the required details (Client Name, Redirect URI, etc.). 3. After saving, copy the **Client ID** shown — store it securely. |
| **Client Secret** *| A confidential string generated alongside your Client ID. It’s used to securely authenticate OAuth requests. | 1. During the API client registration process, Workday will generate a **Client Secret**. 2. Copy and store it securely — it may not be displayed again. |
| **Refresh Token** *| A token that allows your integration to obtain new access tokens without re-authentication. Enables long-term connection to Workday. | 1. Go to the **View API Clients** report. 2. Open the API client you registered. 3. Click the ellipsis (...) → **API Client → Manage Refresh Tokens for Integrations**. 4. Select the Workday user account and click **Generate New Refresh Token**. 5. Copy and store it. |
:::note
You can add a maximum of 15 accounts. Use **+Add account** and proceed with the previous steps to add each accoount.
:::
## Actions supported via AI Agent (Bot)
Once you integrate Workday, you can perform the following actions to directly from the AI Agent conversations:
### Fetch employee information
Retrieve key employee details such as job title, department, manager, employee ID, and contact information. Useful for quick lookups during HR or IT support conversations.
#### Required inputs
* Employee ID (`number`): Unique numeric identifier assigned to each employee in the Workday system.
### Fetch employee time off plan details
View an employee’s time off plan, including accrual policies, available leave balances, and plan eligibility. Helps users better understand their leave entitlements.
#### Required inputs
* Employee ID (`number`): Unique numeric identifier assigned to each employee in the Workday system.
### Get employee time off types for a plan
Return a list of time off types (e.g., vacation, sick leave, personal leave) associated with an employee's time off plan. Ideal for guiding employees during leave application.
#### Required inputs
* Employee ID (`number`): Unique numeric identifier assigned to each employee in the Workday system.
### Apply time off
Allows employees to apply for time off directly through the bot by specifying the number of days and relevant identifiers. Useful for streamlining HR requests and improving employee experience.
#### Required inputs
- **Days** (`:array`): The list of dates for which time off is being requested. Each date should be in the appropriate format (e.g., `YYYY-MM-DD`).
- **Employee WID** (`:string`): The unique Workday ID assigned to the employee. This is required to correctly associate the time-off request with the employee’s record.
### View employee benefits
Provide employees with an overview of their enrolled benefits, including healthcare, insurance, retirement plans, and other offerings. Helps reduce dependency on HR teams.
#### Required inputs
* Effective Date (:string - date): The date for which the benefits information should be retrieved. Format should be YYYY-MM-DD. This helps pull the accurate benefits as of that point in time.
* Employee ID (WID) (:string): The unique Workday ID associated with the employee whose benefit details are being requested.
### Change preferred name
Allow employees to update their preferred name in Workday through a simple conversational flow. This may include updating first and last names, or opting to use the legal name as the preferred name.
#### Required inputs
- **Use Legal Name as Preferred Name** (`:boolean`): Set to `true` if the legal name should be used as the preferred name. If `false`, provide a new preferred first and/or last name.
- **Employee ID** (`:number`): The unique numeric identifier assigned to the employee in Workday.
#### Optional inputs (if not using legal name)
- **Country Reference (ISO_3166-1_Alpha-2_Code)** (`:string`): The country code to determine locale-based formatting and naming standards. Example: `US`, `IN`.
- **First Name** (`:string`): New preferred first name.
- **Last Name** (`:string`): New preferred last name.
### Update marital status
Let employees update their marital status with appropriate documentation or input validation via the bot.
#### Required inputs
- **Employee ID** (`:number`): The unique numeric identifier assigned to the employee in Workday.
- **Marital Status (Marital_Status_ID)** (`:string`): The updated marital status code. Example values may include `SINGLE`, `MARRIED`, `DIVORCED`, depending on your Workday configuration.
### Update home contact information
Empower employees to change their home address, phone number, or other contact details through the bot, ensuring quick and easy updates to personal information.
#### Required Inputs
- **Contact Type** (`:string`): The type of home contact information to update. Values could include `Phone`, `Email`, or `Address`.
---
## Zendesk offline ticketing
Integrating Zendesk with Yellow.ai allows you to create offline support tickets. This ensures that users can raise the offline support requests even when live agents are unavailable.
When live agents are offline, Zendesk’s offline ticketing system allows you to create offline support request. These requests are then converted into support tickets in Zendesk. Once agents are available, they can access these tickets and follow up with users via email to resolve their queries.
**Key benefits of using this Integration**:
* **Creating offline tickets**: Generates the support tickets from offline messages when the agents are unavailable.
* **User management:** Allows the addition of new users, retrieval of user details, and creation of offline support requests within Zendesk.
## Integrate Zendesk Offline Ticketing with Yellow.ai
To integrate Zendesk Offline Ticketing with Yellow.ai, follow these steps:
### Get your domain address & API Key from Zendesk
1. Log in to your [Zendesk account](https://www.zendesk.com/in/login/).
2. From your browser's address bar, copy your Zendesk domain URL. Example: `https://yourcompany.zendesk.com`.
3. Click on the Zendesk icon and select **Admin center**.
3. In the Admin center, go to **Apps and Integrations** > **Zendesk API**.
4. Copy the **API key** and **User name**.
### Add API key and domain to the Yellow platform
1. Login to the [Yellow platform](https://cloud.yellow.ai/) and navigate to the **Development** environment.
* In a two-tier environment, you can only add accounts in the Development environment.
* In a three-tier environment, you can only add accounts in Staging/Sandbox environment.
2. Go to **Extensions** > **Integrations** > **Zendesk offline ticketing**.
2. In **Give account name**, enter a unique name for the account. Supports only lowercase alphanumeric and underscore characters. It is recommended to use a name that aligns with its purpose for better usability.
3. In **API key**, paste the API token you generated from Zendesk.
4. In **Domain name**, enter your Zendesk domain URL (example, `https://yourcompany.zendesk.com`).
5. Enter the **User name** that you have copied from your Zendesk account.
6. Click the **Connect**.
* To connect more accounts, repeat the steps outlined above for each account. You can add a maximum of 15 accounts.
## Manage Zendesk tickets through AI Agent
This integration allows your bot to perform actions such as [get user information](#get-user-details), [adding new users](#add-user), and [creating offline tickets](#create-request) in Zendesk.
1. Navigate to **Automation** > **Node** > **Integrations** > **Zendesk**.
2. Select the Zendesk account that you want to use for managing tickets.
3. Select the desired action:
* **Get user**: Retrieve information about a specific user in Zendesk.
* **Add user**: Create a new user in Zendesk.
* **Create request**: Generate a new support ticket in Zendesk.
### Get user details
This action allows you to retrievie information about a specific user from your Zendesk account. You can get the user details using the External ID or query. For more information, click [here](https://developer.zendesk.com/api-reference/ticketing/ticket-management/search/#query-syntax).
**Node Input Params**:
Field name | Description | Datatype
------------|-------------|----------
External ID | Enter the unique identifier of the user. The API treats the id as case insensitive. Example: "ian1" and "IAN1" are the same value. | String
### Add user
The Add user action creates a new user in your account.
**Node Input Params**:
Field name | Description | Datatype
------------|-------------|----------
Email | Enter the email address of the user. Example: rio.doe@yellow.ai| String
Name | Enter the name of the user. Example: Rio Doe| String |
Role | Enter the user's role within Zendesk. Supported roles: end-user, agent, admin. Default is end-user. | String |
Custom role ID | Enter custom role ID, if the user is an agent on the Enterprise plan or above | String |
Default group ID | Enter ID of the user's default group| String |
External ID | Enter the unique identifier of the user | String |
Locale | Enter user's locale (language). If both locale and locale_id are provided, locale_id is ignored. | String
Locale ID | Enter user's language identifier | Number
Notes | Enter any additional notes about the user| String
Organization ID | Enter the ID of the user's organization. If the user has [organization memberships](https://developer.zendesk.com/api-reference/ticketing/organizations/organization_memberships/) memberships, this ID represents the default organization. | Number
Phone | Enter the user's primary phone number | String)
Tags | Enter the tags associated with the user. Only applicable if user tagging is enabled in your account | Array
**Sample response:**
```json
{
"user": {
"name": "John Doe",
"email": "john.doe@example.com",
"role": "end-user",
"custom_role_id": 123,
"default_group_id": null,
"external_id": null,
"locale_id": 1176,
"notes": null,
"organization_id": null,
"tags": []
}
}
```
### Create request
Use this action to submit support requests. These will be converted into offline tickets in your Zendesk account.
**Node Input Params**:
Field name | Description | Datatype
------------|-------------|----------
Comment | Describe the problem, incident, question, or task. For more informtion, see [Request comments](https://developer.zendesk.com/api-reference/ticketing/tickets/ticket-requests/#request-comments) | Object
Priority | The priority of the request. Acceptable values are "low", "normal", "high", or "urgent". | String
Requester | Required for anonymous requests. Specifies the requester of the anonymous request. For more details, see [Creating anonymous requests](https://developer.zendesk.com/documentation/ticketing/managing-tickets/creating-and-managing-requests/#creating-anonymous-requests) | object
Subject | The subject of the request. If the subject field is visible to end users, this value is used; otherwise, a truncated version of the description is used. | string
Tags | Enter the tags associated with the user | Array
Via | Describes how the object was created. See the [Via object reference](https://developer.zendesk.com/documentation/ticketing/reference-guides/via-object-reference/) | Object
**Sample response:**
```json
{
"request": {
"requester": {
"name": "Rio",
"email": "rio@yellow.ai"
},
"subject": "Test ticket",
"comment": {
"body": "test ticket"
},
"priority": "urgent",
"via": {
"channel": "chat"
},
"tags": [
"yellow_handoff",
"GoFan_Support"
]
}
}
```
---
## Zoho CRM
You can integrate Zoho CRM with Yellow.ai to allow syncing of customer data, and improve customer engagement. This integration enables you to effortlessly create, update, and search for records within various modules of Zoho CRM.
:::note
Yellow.ai supportes integration with both **Zoho CRM** and [Zoho SalesIQ](https://docs.yellow.ai/docs/platform_concepts/appConfiguration/zoho-live-chat).
:::
## Supported Zoho CRM actions with Yellow.ai
Action | Description |
|---------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|
| createRecord | Creates a record in the integrated Zoho CRM account. The following are the modules in which records can be created: 1. Home2. Leads3. Contacts4. Accounts5. Deals6. Tasks7. Events 8. Activities9. Invoices10. SalesInbox11. Campaigns12. Vendors 13. PriceBooks14. Cases15. Solutions16. Documents17. Forecasts18. Visits19. Social 20. Notes21. Attachments22. Actions Performed |
| updateRecord | Updates a record in the integrated Zoho CRM account in the following modules: 1. Leads2. Contacts3. Accounts4. Deals5. Tasks6. Events 7. Activities8. Invoices9. SalesInbox10. Campaigns11. Vendors 12. PriceBooks13. Cases14. Solutions15. Documents16. Forecasts17. Visits18. Social 19. Notes |
| searchRecord | Fetches a particular record in the integrated Zoho CRM account in the following modules:1. Leads2. Contacts3. Accounts4. Deals5. Tasks6. Events 7. Activities8. Invoices9. SalesInbox10. Campaigns11. Vendors 12. PriceBooks13. Cases14. Solutions15. Documents16. Forecasts17. Visits18. Social 19. Notes|
## Connect Zoho CRM with Yellow.ai
**Prerequsites:**
1. An active Zoho CRM account
2. An active yellow.ai account.
To connect your Zoho CRM account with Yellow.ai, follow the these steps:
Add accounts only in the development or staging environment. You can access the connected accounts in the Live/Production environment.
1. On the left navigation bar, go to **Extensions** > **Integrations**.
2. Navigate to **CRM** > **Zoho CRM**. Alternatively, you can use the Search box to find the integration app.
3. Under **Give account name**, provide a unique identifier. Only lowercase alphanumeric characters and underscores (_) are allowed.
4. Go to your **Zoho account** > **Profile settings** to identify your data center location.
5. Based on your Zoho profile, choose the matching data center from the options listed in the drop-down.
6. You need to sign-in to your Zoho CRM account. Once you have signed-in, click **Accept** to authorize Yellow.ai to access **Zoho CRM**.
5. You can add up to 15 accounts. To add another Zoho CRM account, click on **Add account** and follow the steps mentioned above.
## Use actions in bot conversations
To carry out a [certain action](#supported-zoho-crm-actions-with-yellowai) in your Zoho CRM account, follow these steps:
1. Go to **Automation** and [create a flow](https://docs.yellow.ai/docs/platform_concepts/studio/build/Flows/journeys#2-create-a-flow) based on your requirement.
2. In whichever point you want the bot to access Zoho CRM, inlcude the Zoho CRM node. For that drag the node connector, go to **Integrations** > **Zoho CRM**.
3. In the **Zoho CRM** node, fill the following:
* **Account name:** Choose the Zoho CRM account. If you have only one account, the account name is automatically populated. If you have multiple accounts, the first account added is auto-populated. Select the one you want to use at that moment.
* **Action:** Choose the [action](#supported-zoho-crm-actions-with-yellowai) to be performed.
* **Select Objects:** Choose the Zoho CRM module in which the chosen action should be performed.
* Depending on the selected object, the corresponding fields will be shown. To fill those fields, you need to collect it as an input from users beforehand. Construct the flow accordingly and [store the data in variables](https://docs.yellow.ai/docs/platform_concepts/studio/build/bot-variables#41-store-data-in-variables). These variables will then be passed in those fields.
4. Each Zoho CRM action returns a response as a JSON object. [Store that response in an object variable](https://docs.yellow.ai/docs/platform_concepts/studio/build/bot-variables#41-store-data-in-variables) and to extract the required information from the payload, [pass that variable](https://docs.yellow.ai/docs/platform_concepts/studio/build/bot-variables#42-retrieve-data-from-variables) in a [message node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/message-nodes1/message-nodes) to display that response to the end user.
For example, if you receive the following response, you can use this syntax ``` {{{variables.variablename.data.0.Owner.name}}} ``` to display only the account owner's name.
```
{
"data": [
{
"Owner": {
"name": "Bhaskar K",
"id": "231200000000180001",
"email": "karanam.bhaskar@yellow.ai"
},
"Company": null,
"Email": "bhaskar@abcl.com",
"$currency_symbol": "$",
"id": "231200000000321003",
"$approved": true,
"Created_Time": "2021-10-05T11:52:54+05:30",
"Created_By": {
"name": "Bhaskar K",
"id": "231200000000180001",
"email": "karanam.bhaskar@yellow.ai"
},
"First_Name": "Bhaskar",
"Full_Name": "Bhaskar K",
"Modified_By": {
"name": "Bhaskar K",
"id": "231200000000180001",
"email": "karanam.bhaskar@yellow.ai"
},
"Phone": "9087654321",
"Modified_Time": "2021-10-05T11:52:54+05:30",
"$converted_detail": {},
"$approval_state": "approved"
}
],
"info": {
"per_page": 200,
"count": 1,
"page": 1,
"more_records": false
}
}
```
---
## Zoho SalesIQ
## Scope of Integration
Yellow.ai Integration with Zoho Live Chat allows you to seamlessly connect your Zoho SalesIQservice with the yellow.ai platform. Any customer who has a Zoho SalesIQ account will be able to seamlessly connect their service with yellow.ai using Oauth. This connector will enable it to connect end users to live agents.
## Configuration
Setting up an account for Zoho SalesIQ :
1. You can create an account on Zoho and use [this](https://api-console.zoho.com/add?client_type=ORG) link to create a client. Use appropriate top level domain according to your location (for example .in for Indian users).
2. Set [this](https://cloud.yellow.ai/integration/oauth/zoho-live-chat) as a redirect URI. You'll need client Id and client secret for connection which you'll get on the "Client Secret" tab on the same window.
3. Then you can navigate to the salesIQ dashboard where you can find your screen name in the URL.
4. You can find Department Id in the settings section. For App Id, you'll need to call [this](https://www.zoho.com/salesiq/help/developer-section/rest-api-apps-list.html) API with appropriate credentials.
Simple Integration with client ID, Client Secret, Screen Name, App ID and Dept ID:
Once you have all these credentials, you can connect with Zoho Live Chat integration on yellow.ai dashboard.
For connecting, you'll need to navigate to the integrations page and search for Zoho Live Chat integration.
On this screen you need to enter Client ID, Client Secret, Screen Name, App ID and Dept ID.
After that you can click on the Connect to Zoho Live Chat button to be prompted for the Oauth process where you need to give us access to your account for:
1. Initiating the conversation
2. Creating webhook
3. Viewing webhook
4. Deleting webhook.
After you click accept, a webhook will automatically be created on your SalesIQ dashboard, which will empower the user-agent conversation.
If you have multiple accounts, follow the above mentioned steps to add each of them.
:::note
1. Enter a unique name for each account to easily identify them within the yellow.ai platform. It is recommended to use a name that aligns with its purpose for better usability.
2. You can add a maximum of 15 accounts.
3. In a two-tier environment, such as bots with only Development/Live environments, you can add account names only in the development mode. Once added and flows have been built, in the Live mode, you can only choose the account names and not edit them.
4. In a three-tier environment, such as bots with Staging/Sandbox/Production modes, in Staging and Sandbox modes, you can add and edit new accounts. However, in Production, only the account details added in Staging will be available. You can only map in the production environment.
:::
## Use Case
:::info
Use **Ticket-closed** in the **Raise Ticket node** to perform specific actions when a live chat closes, instead of using the **ticket-close** event.
:::
- In this integration you can use **raise ticket** node to create a conversation with Zoho SalesIQ agent and once conversation initiates the user can talk to the agent.
:::note
When multiple accounts are added, select the appropriate account for each node, allowing you to leverage the unique functionalities of each account for their intended purposes.
:::
### Events
Following are the events which are currently accommodated in the Integration:
Event | Description
----- | -----------
zoho_operator_replied | This event reaches to bot when a salesIQ agent replies to the user.
ticket-closed | This event reaches to bot when salesIQ agent closes the user ticket.
:::info
If you have added multiple accounts in your platform, enable events for each of those accounts.
:::
## Limitations
- Images, audio or video attachments are being supported only from the user side currently. Attachments from agents are not supported.
## Steps to perform if webhook deletion fails while disconnecting the integration:
1. Check if you can access the webhook page on the client dashboard
2. If you can access it, please try to delete it manually from the dashboard itself.
3. If you can't access it, please address the reason why you are not able to access it. (for example, the plan needs to be upgraded or the free trial expired).
- Navigate to Settings -> Webhooks.
- If your free trial has expired for Zoho SalesIQ, you will see the above error.
- Please upgrade the plan if you need to register/ deregister webhooks for live chat use cases.
- If you can view the webhook, then please try to delete it manually.
# Reference
API Documentation: [https://www.zoho.com/salesiq/help/developer-section/rest-api-v2.html](https://www.zoho.com/salesiq/help/developer-section/rest-api-v2.html)
---
## Agent Best Practices
These are the practices that consistently produce good Nexus bots. They come from teams that have shipped Nexus agents to production - read them once when you start, and revisit them before each release.
Flip through them as flashcards - try to answer each question before you reveal it - or switch to **Read as article** for the full text.
## Start small {#start-small}
The single biggest mistake new builders make: building five agents on day one.
**Do this instead:**
1. Start with just the bot's configuration. Get it answering 80% of common questions correctly.
2. Look at real (or test) transcripts. Find the place the bot consistently fails.
3. *Then* introduce an agent or a tool to handle that case.
Extra agents add complexity. Add them deliberately, not preemptively.
The same restraint applies to tools *within* an agent. An agent with a long tool list and lots of inline "decide, then call, then decide again" logic becomes unpredictable - every extra tool is one more thing routing has to choose between, and every inline decision is a place the model can drift. Keep an agent's job conversational: understand the user, pick the right next step, talk back. Push deterministic multi-step logic - call API, branch on the result, call another API, format the output - into a **workflow** and attach it as a single tool the agent calls. The agent owns the conversation; the workflow owns the procedure. If you find an agent juggling many tool calls per turn, that's the signal to move the orchestration into a workflow (or a [guided agent](../build/guided-agents/index.md)).
## Treat bot identity as a contract {#treat-bot-identity-as-a-contract}
Your **bot identity** is the most important field on the entire platform. It's also the field most builders treat carelessly.
**Do this:**
- Lead with role, then responsibilities, then constraints, then tone.
- Be concrete about what the bot must NOT do. "You never quote pricing" stops bad behavior; "You're a helpful assistant" doesn't.
- Stable identity = stable behavior. Don't tweak identity casually - every change ripples through every conversation.
**Don't do this:**
- Don't write marketing copy. ("You're the best assistant on Earth!" - the model will not behave better.)
- Don't be vague. ("You help customers with anything" gives the model no constraints.)
- Don't pile on contradictions. ("Be brief. Always explain in detail.")
## Writing prompts {#writing-prompts}
Every prompt field rewards the same habits: short plain sentences, one instruction per line, concrete do's and don'ts, and saying what *not* to do as clearly as what to do. The bot identity above is the headline example, but the detailed, field-by-field guidance lives with each surface - keep this page as the index and follow the links:
- **Agent instructions and Triggers** - keep *when to take over* (Trigger) separate from *how to behave* (Agent instructions); see [Conversational agents → Writing agent instructions](../build/agents/conversational-agents.md#writing-agent-instructions).
- **Memory variables** - name only the variables a later turn actually reads, and prefer tool input mapping for single-turn values; see [Memory in Nexus agents](../build/configuration/memory.md).
- **Tool descriptions and calling** - write descriptions like a docstring (what / inputs / when / when-not) so the model calls the right tool with the right arguments; see [Tools - Best Practices](./tools.md).
## Pick rules carefully {#pick-rules-carefully}
There are two rule lists, and people mix them up:
| | Conversation Rules | Routing Logic |
|---|---|---|
| **What it shapes** | Tone, do's and don'ts | Where messages get routed |
| **Available on** | Nexus and the legacy platform | Nexus only |
| **Use when…** | "The bot should always confirm before submitting" | "Billing questions must go to billing-agent" |
Both have the same per-rule limits in the studio (20-500 characters). Both let you add many rules.
**Best practices:**
- One rule, one concern. Compound rules are hard to debug.
- Phrase positively when possible - "Confirm the order ID before sharing details" beats "Don't proceed without an order ID."
- Test each rule with a single, dedicated test prompt. If you can't write that test, the rule is too vague.
## Don't ship static welcome and fallback strings {#dont-ship-static-welcome-and-fallback-strings}
A hardcoded "Hi! How can I help?" works for a hackathon, not for production. In Nexus, both Welcome and Fallback let you go dynamic:
- **Welcome → Instruction** lets the model pick the right opening based on context (returning user vs new, logged-in vs anonymous, channel-specific tone). Welcome can also trigger a **welcome workflow** if the greeting needs to look something up first (loyalty status, account info).
- **Fallback → Instruction** lets the model do real recovery - rephrase the user's intent, suggest a likely topic, or offer a hand-off - instead of a generic apology string. Pair it with the **Retries** count for validation failures.
If your welcome or fallback needs to *act* (search the KB, route to a human, render rich media), reach for a workflow - either picked directly in the welcome picker, or invoked as a **workflow** or **knowledge-base** tool the model calls from the Instruction prompt.
## Don't put everything into Memory {#dont-put-everything-into-memory}
Memory in Nexus isn't a context-window slider - it's a typed key-value store, shared across all agents in a conversation (see [Memory](../build/configuration/memory.md)). The temptation is to stash everything you might need later. Resist it.
**Why restraint matters:**
- Every variable you declare becomes a prompt input. More variables = larger prompts = more cost and latency per turn.
- Two agents writing to the same variable name silently overwrite each other.
- Memory persists for 2 days. Single-turn values don't belong there - pass them through tool input mapping instead.
**Best practice:** start with the minimum. Add a variable only when you can name the specific later turn (or specialised agent) that needs to read it.
## Turn safety filters on before you ship {#turn-safety-filters-on-before-you-ship}
If your account has **AI Safety & Conduct**:
- Enable customer-query filters and AI-response filters before going live.
- Test adversarial prompts (jailbreaks, off-topic, hostile) in [Testing Lab](../test-debug/index.md).
- Pair filters with a fallback that says something safe and helpful when a filter fires - silence is worse than a graceful redirect.
## Test like you mean it {#test-like-you-mean-it}
The Nexus testing tools are good. Use them.
- **Playground** (▶ on each agent) - test individual conversations as a user would.
- **AI Trust Centre → Dataset** - store a curated set of test cases.
- **AI Trust Centre → Testing Lab** - bulk-replay your dataset before every release.
A typical regression suite has 10-30 test cases covering: golden-path successes, common edge cases, every routing rule, every tool, and a few adversarial prompts. Saving these once pays for itself the first time you tweak identity and need to verify nothing regressed.
## Voice ≠ chat {#voice--chat}
If your bot serves voice:
- Lower memory than chat (latency matters more).
- Lower validation retry limits (failed retries compound latency).
- Test in the **Voice Playground** specifically - TTS pacing, interruptions, and barge-in behave differently than chat.
## Build a release checklist {#build-a-release-checklist}
Before each release:
- [ ] Identity changes reviewed and approved by stakeholders
- [ ] All routing rules have a test prompt that proves they fire
- [ ] Fallback uses an Instruction that can recover gracefully (not a static apology)
- [ ] Safety filters enabled and tested with adversarial prompts
- [ ] Regression dataset replayed and passing
- [ ] Voice playground spot-checked (if voice channel)
The first time this checklist saves you from a regression, you'll keep using it forever.
## When to ask for help {#when-to-ask-for-help}
If your bot is doing something genuinely puzzling - wrong agent fires consistently, identity instructions seem ignored - open the **Playground** (▶ on the misbehaving agent) and re-send the message. Read the bot's reply carefully, then re-check the agent's Trigger, identity, and any Routing Logic rules - most "weird behavior" traces back to one of those three.
---
## Tools - Best Practices
Practical patterns from teams running Nexus agents in production. Read once before you start, revisit before each release.
Flip through them as flashcards - try to answer each question before you reveal it - or switch to **Read as article** for the full text.
## Naming {#naming}
- **Verb-first, scoped to the domain.** `getOrderStatus`, `updateAddress`, `escalateToBilling`. Avoid `tool1`, `helper`, `doStuff`.
- **Keep names stable.** Tool names show up in routing rules and traces. Renaming is a chore - pick well the first time.
- **One name, one purpose.** Don't reuse `lookup` for three different tools across domains. Be specific: `lookupOrder`, `lookupCustomer`, `lookupTicket`.
## Descriptions {#descriptions}
The description field is the most important text on the page. The LLM reads it to decide *whether* to call your tool. Treat it like a function docstring written for a junior teammate.
A good description answers all four:
1. **What does the tool do?** ("Look up a customer's current shipment status…")
2. **What inputs does it need?** ("…by order ID.")
3. **When should it be used?** ("Use when the user asks about an existing order.")
4. **When should it NOT be used?** ("Do not use for new orders or pricing questions.")
Omitting any of these makes the LLM guess.
## Input schema {#input-schema}
- **Always include `description` for each property.** Naming a field `orderId` is half the message; describing it as "The customer's order ID, typically a 10-character alphanumeric string" closes the loop.
- **Mark requireds explicitly.** Without `required`, the LLM may call your tool with missing arguments.
- **Use `enum` for fixed sets.** Enum values prevent the LLM from inventing inputs.
- **Keep schemas small.** Every input is one more thing the LLM has to extract correctly. Cut what's not strictly needed.
- **Don't ask for what you can derive.** If the user is authenticated and you have their email in session state, don't ask the LLM to extract their email.
## Output schema {#output-schema}
- **Always define one.** Without an output schema, the LLM doesn't know how to read the response.
- **Match the actual shape.** If your workflow returns `{status, trackingNumber}`, your output schema should declare exactly those keys.
- **Use clear types.** Don't return numbers as strings or vice versa. The LLM will get confused.
## Granularity {#granularity}
**One tool, one job.** A tool that does five things via a "mode" parameter is harder for the LLM to use correctly than five focused tools.
✅ Good:
- `getOrderStatus(orderId)`
- `cancelOrder(orderId, reason)`
- `updateShippingAddress(orderId, newAddress)`
❌ Bad:
- `manageOrder(orderId, action: "status" | "cancel" | "updateAddress", ...)` - the LLM will mis-pick the action.
## Choose the right tool type {#choose-the-right-tool-type}
| You want to… | Use |
|---|---|
| Run multi-step backend logic, hit an API, branch on data | **Workflow tool** |
| Answer from your documents and FAQs | **Knowledge Base tool** |
| Hand off a chat to a human | **Escalate to Agent** |
| Forward a voice call to a human | **Transfer Call** |
| Hit a single REST endpoint (no branching) | Wrap in a one-step workflow today; **HTTP Webhook** when it ships |
| Connect a custom data source | **Connect MCP Server** when it ships |
When two types could work, pick the more specific one. KB > workflow for content questions. Escalate to Agent > workflow for handoffs.
## Test before you save {#test-before-you-save}
The **Test** tab in the configuration drawer exists for a reason. Use it.
- Run the tool with a realistic input. Confirm output is what you expect.
- Run it with a missing/invalid input. Confirm it fails gracefully.
- For workflow tools, run with mocks during development so you don't burn through production data or paid API credits.
## Make critical tools deterministic {#make-critical-tools-deterministic}
The LLM will *usually* pick the right tool from descriptions alone. For anything critical - escalations, payments, account changes - don't rely on usually. Add a Routing Logic rule:
> "If the user asks about billing, you must call the **getInvoice** tool before composing a reply. Do not answer billing questions from memory."
See [Routing Logic](../build/configuration/routing-logic.md).
## Tool descriptions and routing rules work together {#tool-descriptions-and-routing-rules-work-together}
- Descriptions tell the LLM *how* the tool works.
- Routing rules tell the LLM *when* to use it.
Both matter. A great description with no routing rule means the LLM is guessing in ambiguous cases. A great rule with a vague description means the LLM may call the tool with bad arguments.
## Iterate on real conversations {#iterate-on-real-conversations}
Your first guesses about descriptions and schemas will be wrong in places. The fix loop:
1. Run a batch of test conversations in **AI Trust Centre → Testing Lab**.
2. Open the **Playground** (▶ on any agent) and re-run the failing input - watch how the agent uses the tool's output.
3. Look at where the bot picked the wrong tool, missed inputs, or misread output.
4. Adjust the offending tool's description / schema.
5. Re-run.
Three rounds of this beats six months of "it should work."
## Keep the catalog tidy {#keep-the-catalog-tidy}
- **Delete tools you no longer use.** The LLM sees every available tool. Stale tools dilute its decisions.
- **Don't keep "test" tools in production.** If you need a sandbox tool, build it in a non-prod bot.
- **Document the catalog.** Keep a brief external doc - a Notion page, a wiki - listing every tool, what it does, and who owns it. Future builders will thank you.
## Pre-release checklist {#pre-release-checklist}
- [ ] Every production tool has a clear description with when-to-use and when-not-to-use.
- [ ] Every input schema has property descriptions and `required` set correctly.
- [ ] Output schemas match what the underlying workflow / KB / API actually returns.
- [ ] Critical tools (escalation, payments, account changes) have a Routing Logic rule.
- [ ] Each tool tested in isolation via the Test tab.
- [ ] Stale or test tools removed from the catalog.
- [ ] Regression dataset includes test cases for every tool path.
## Common mistakes {#common-mistakes}
- **Vague descriptions.** "Order tool" tells the LLM nothing useful.
- **Ten-input schemas.** The LLM will fail to extract all of them. Trim.
- **No output schema.** The LLM ignores the response or hallucinates.
- **Five overlapping tools.** Two tools with similar descriptions confuse the LLM. Sharpen each so triggers are distinct.
- **Forgetting Routing Logic for critical paths.** Hoping the LLM picks the right tool every time is wishful thinking.
- **Skipping the Test tab.** "It looked right in the config" is not the same as "it works."
- **Leaving stale tools in the catalog.** Every unused tool is noise the LLM has to filter out.
---
## Voice - Best Practices
Practical guidance from teams shipping Nexus voice bots. Read once before launch, revisit before any voice-related change.
Flip through them as flashcards - try to answer each question before you reveal it - or switch to **Read as article** for the full text.
## Pick the right runtime mode {#pick-the-right-runtime-mode}
| If your goal is… | Pick |
|---|---|
| Production voice bot, broad provider/language support, full custom voice access | **Text & TTS (pipeline)** |
| Lowest possible latency for a short demo, with a small voice catalog | **Realtime Audio** |
| Anything multilingual or with a custom-cloned voice | **Text & TTS (pipeline)** - Realtime can't use your custom voices |
Most production deployments stay on Text & TTS for the lifetime of the bot. Don't switch modes unless you have a specific reason.
## Pick the right TTS provider {#pick-the-right-tts-provider}
| Provider | Sweet spot |
|---|---|
| **Yellow AI** *(default)* | Broad coverage, full custom-voice support. Right default for most bots. |
| **ElevenLabs** | Best-in-class English voice quality. Premium voices for high-stakes brand interactions. |
| **MiniMax** | Multilingual presets including Mandarin. Good for Asia-Pacific deployments. |
Don't switch providers per agent within the same bot if you can avoid it - keeps the brand voice consistent.
## Pick the right STT (speech recognition) {#pick-the-right-stt-speech-recognition}
Yellow AI is the default and right for most cases. Switch only when:
- Your audience speaks a language Yellow handles less well - try Deepgram, Sarvam (Indic), or Microsoft Azure.
- You're getting consistently bad transcripts despite good audio - try a different provider as a diagnostic.
Test STT with **real recordings of your audience**, not just your own voice. Accents, background noise, and domain vocabulary all matter.
## Cloning a voice {#cloning-a-voice}
- **Record clean.** A 5-second clean clip beats a 30-second noisy one. Quiet room, good mic, single take.
- **Read the suggested sample text.** It's tuned for clean clones.
- **Name for the voice character, not the use case.** "Aria - warm support EN" beats "Customer Support Voice."
- **Test cloned voices in the [Voice Playground](../voice/testing.md)** *and* on a real phone before assigning to a production bot.
## VAD tuning {#vad-tuning}
Default values (threshold 0.85, prefix 300 ms, silence 500 ms) are right for most calls. Don't tune speculatively.
When you do tune:
- Slow / non-native speakers → raise silence duration to 700-800 ms.
- Fast-paced sales / outbound → drop silence duration to 300 ms.
- Noisy environments → raise threshold to 0.9.
Tune one knob at a time, retest, and document why you changed it.
## Voice instructions vs bot identity {#voice-instructions-vs-bot-identity}
- **Bot identity** says *what the agent does and is*.
- **Voice instructions** say *how it speaks* - pace, language, tone delivery.
Don't repeat identity in voice instructions. Layer, don't duplicate.
## Latency {#latency}
Conversational voice feels broken above ~2 seconds end-to-end (user finishes speaking → user hears reply start). Aim for under 1.5 seconds.
Where latency hides:
- **Slow model** - large prompts, slow model choice. Trim the system prompt and try a faster model.
- **Slow KB lookup** - too many results, too-aggressive history concatenation. Tune the KB tool.
- **Slow TTS** - provider choice, voice choice. Some voices are slower to start than others.
- **VAD too patient** - silence duration high. Drop it.
- **Telephony round-trip** - fixed cost; can't tune from the bot config.
Measure before you optimize. Isolate model latency from TTS latency by swapping each in turn and re-testing in the Voice → Telephony Web Call.
### Tool-call acknowledgements (`_voice_ack`)
The other big latency hide is the **silent gap on tool calls**. When the model dispatches a tool call (KB lookup, workflow, API call), the tool may take a second or two to return. Without anything to play, TTS goes silent - and to a voice user that silence reads as "the bot is broken."
Nexus voice handles this automatically. On voice channels, the runtime decorates every tool's parameter schema with a `_voice_ack` field - a short spoken phrase the LLM is expected to fill in whenever it dispatches a tool ("Let me check that for you", "One moment while I pull that up"). The runtime emits the `_voice_ack` value to TTS immediately, then strips it from the tool's actual arguments so the tool implementation never sees it.
You don't configure `_voice_ack` - it's automatic on voice channels. **But:**
- If the model skips the field (uncommon, but happens), the runtime falls back to your bot's static `toolCallFiller`. Make sure you've set a sensible fallback ("One moment.") in the voice config.
- The acknowledgement is one short utterance per tool call, not a sentence per argument. If a tool routinely takes more than 3 seconds, follow up the ack with a second message inside the tool's response stream rather than relying on the ack alone to cover the wait.
- Realtime Audio mode (OpenAI Realtime) handles this differently - see [Voice on Nexus](../voice/index.md) for the realtime-mode notes.
## Multilingual voice bots {#multilingual-voice-bots}
- **Set the spoken language explicitly in voice instructions.** "Respond in Hindi" is more reliable than expecting language detection.
- **Cloned voices generalize across languages**, but always test in the target language before going live.
- **STT accuracy varies dramatically by language.** Pick the STT provider that's best for your audience's language(s) - not just the default.
## Escalation paths {#escalation-paths}
A voice bot without an escalation path is a customer service liability.
- Add a **Transfer Call** tool. Wire it to a human destination.
- Add a Routing Logic rule that forces escalation on explicit triggers ("agent", "human", "representative", or repeated failure).
- Customize the escalation announcement so the user knows what's happening.
See [Escalation tools](../build/tools/escalation.md).
## Recording compliance {#recording-compliance}
Recording rules vary by jurisdiction. Before enabling recording:
- Confirm the legal posture for each region you operate in.
- Add a clear consent prompt at the start of the call when required.
- Configure the **Recording action** on Transfer Call tools according to policy.
When in doubt, talk to legal before launch.
## Pre-launch checklist {#pre-launch-checklist}
- [ ] Voice mode set deliberately (Text & TTS for production, Realtime only for narrow use cases).
- [ ] Provider and voice tested on a real call, not just the playground.
- [ ] Cloned voices (if any) tested in target languages.
- [ ] VAD tuned for the audience's speaking pace and environment.
- [ ] Voice instructions cover language and pace explicitly.
- [ ] Telephony provider configured for inbound and outbound.
- [ ] Caller ID set sensibly.
- [ ] Escalation tool wired and tested end-to-end.
- [ ] Fallback wired to a human-handoff workflow (not a generic apology string).
- [ ] Recording compliance reviewed for each region.
- [ ] Voice regression suite (5+ real test prompts) defined and run before each release.
## Common mistakes {#common-mistakes}
- **Switching voice providers casually.** Each provider has different voice character and latency profile. Customers notice.
- **Skipping outbound testing.** "It sounds great in WebRTC" doesn't mean it sounds great over PSTN.
- **Tuning VAD without measurement.** Random changes usually make things worse.
- **No escalation path.** A frustrated voice user without a human option churns immediately.
- **Long welcomes.** Voice users tolerate even shorter intros than chat users. Get to the point.
- **Multilingual without locking the language.** Don't trust auto-detection in production. State the language in voice instructions.
- **Not listening to real calls.** Production recordings (where compliant) are the only ground truth. Schedule time to listen.
Return to: **[Voice Overview](../voice/index.md)**.
---
## Widget Builder Best Practices
Practical tips from teams that have shipped widgets to production. Skim before you start, revisit before each release.
Flip through them as flashcards - try to answer each question before you reveal it - or switch to **Read as article** for the full text.
## Decide if you really need a widget {#decide-if-you-really-need-a-widget}
Before opening Widget Builder, ask: can I do this with a rich message or a flow?
| Use case | Reach for |
|---|---|
| Quick replies, a carousel, a single short input | Rich message node |
| Custom UI with multiple fields, conditional logic, or its own UI state | **Widget** |
| Branching logic with no UI | Flow or agent |
Widgets are powerful, but they cost more to build and maintain than rich messages. Use them when you genuinely need custom UI.
## Schema design {#schema-design}
- **Keep inputs flat.** Deeply nested `properties` are harder to bind in flow nodes and harder to debug in traces.
- **Mark requireds explicitly.** Without the `required` array, the flow node won't warn you about unfilled inputs at design time.
- **Use `enum` for known sets.** "status: pending | approved | rejected" is clearer and validates for free.
- **Don't over-ask.** Inputs you don't actually use just slow everyone down — yourself included.
## State design {#state-design}
- **Default state is for local UI only.** The selected option, the active step, the form errors. That's it.
- **Don't put session or account data here.** That belongs in agent state, fetched from a tool, or passed in via schema.
- **Keep state shallow.** A flat object with primitives is the safest to serialize and the easiest to debug.
- **Don't duplicate schema inputs.** If `userName` came in via schema, read it from props — don't copy it into state.
## Output design {#output-design}
- **Match output keys to what the next flow node expects.** If the next node reads `selectedSlotId`, name your output `selectedSlotId`. Renaming downstream is more painful than picking the right name once.
- **Emit on submit, not on every change.** Continuous emissions clutter traces and rack up turn counts.
- **Keep output flat.** Same reasoning as schema — agents read these by key.
## Naming and slugs {#naming-and-slugs}
- **Names are user-facing; slugs are stable.** The slug (`widget_TkpB0njZg9`) is auto-generated and used by flows. Rename a widget freely — the slug doesn't change, so existing flows keep working.
- **Pick descriptive names.** `BookingForm — APAC` beats `Form2`. Names appear in the saved-widget list and in the flow's rich-media picker.
## Versioning (or lack thereof) {#versioning-or-lack-thereof}
There is no built-in versioning of widget content. Saving overwrites the previous content. For a major redesign:
1. Save a copy of the current widget under a new name (`MyWidget — v2 draft`).
2. Wire the copy into a test flow.
3. Validate end-to-end in the Playground (▶ on the agent that emits the widget).
4. Switch your production flow over to the new widget.
5. Delete the old one (or keep it around briefly as a rollback option).
## Performance {#performance}
- **Cap widget complexity.** Hundreds of dynamic children in one widget will hurt mobile rendering. If a widget feels heavy, split it across two flow nodes that each show a smaller widget.
- **Avoid heavy work in render.** Move computation into event handlers or out to a tool call.
- **Watch the trace.** If a turn that includes a widget has surprising latency, the trace will show whether it's the widget render or something upstream.
## When to use widgets vs. simpler alternatives {#when-to-use-widgets-vs-simpler-alternatives}
**Use a widget when:**
- You need persistent local state across user clicks within the same node.
- The UI has conditional logic (show this if that).
- The interaction is multi-step.
**Use a rich message when:**
- The interaction is a single quick reply, carousel, or short input.
- You don't need local state.
- A standard component would do.
**Use a flow when:**
- The branching is purely backend logic, no UI involved.
## Voice considerations {#voice-considerations}
If your widget can be triggered from a voice channel:
- **Provide a voice-friendly fallback** for any UI-only affordance. A button with no spoken equivalent confuses voice users.
- **Keep the output shape identical** for voice and chat. The agent should be channel-agnostic when reading your output.
- **Test the voice path explicitly** in the Voice Playground — TTS phrasing, pacing, and barge-in behave differently than chat.
## Pre-launch checklist {#pre-launch-checklist}
Before pushing a widget into a live conversation:
- [ ] Schema marks every required input.
- [ ] Default state has values for every key the JSX reads.
- [ ] Output keys match what the next workflow node expects.
- [ ] Widget renders correctly with realistic test inputs in the builder preview.
- [ ] Widget renders inside the Playground (▶ on the agent), not just in the builder preview.
- [ ] The agent reads the widget output correctly in the next turn (re-send the same prompt and watch the reply).
- [ ] Voice fallback exists if the widget runs on voice.
## Common mistakes {#common-mistakes}
- **Building a widget for a one-field input.** Use a prompt node instead.
- **Forgetting `required` in schema.** Loops back as confused flow owners and silent failures.
- **Naming widgets `Form1`, `Form2`.** Two months later, nobody knows which one is which.
- **Editing a live widget's schema without warning.** Breaks every flow that depends on it. Coordinate with flow owners first.
- **Skipping the Playground test.** "It looked fine in the builder preview" is not the same as "it works in a real conversation."
---
## Conversational agents
A **conversational agent** is an LLM-driven specialist: it understands the question, asks for anything it's missing, and works out each reply on its own from your instructions and knowledge. It's the right choice for open-ended work - troubleshooting, support, and anything where the path depends on what the user says. (The deterministic, flow-based alternative is a [guided agent](../guided-agents/index.md), which runs a fixed set of steps in the same order every time. To pick between the two and create one, start at [Create an agent](create.md).)
Ask the [Nexus AI Layer](../../ai-layer/index.md) to create an agent and a starter tool in one go - it scaffolds the agent, writes a trigger, and wires the tool, then waits for your confirmation before saving.
## Agents in one minute
A conversational agent is a specialised assistant designed for one job. You might have an **order-status agent** that answers "Where's my order?", a **demo-booking agent** that helps prospects pick a time, a **billing agent** that handles refunds and invoices. Each has its own:
- Persona and identity
- Conversation rules
- Welcome and fallback
- Tools
When a message belongs to a specialty - say, the user asks "Can I get a refund on order #4421?" - the conversation is handed off to the billing agent. That agent runs the conversation until it's done, then control returns to the bot's configuration.
Agents can also follow their own rules (separate from the rules in your configuration). Most of the time the configuration's rules are enough; reach for per-agent rules only when one agent genuinely needs a different policy (a stricter tone for legal, a softer one for support).
## When to add an agent
Add an agent when:
- You have a clearly **distinct domain** with its own knowledge, vocabulary, or process. *Example:* order-tracking lives in a different world from demo-booking - make them separate agents.
- The domain has its own tools or workflows that other parts of the bot don't need. *Example:* the billing agent calls a refund workflow; no other agent needs it.
- You'd describe the work as belonging to a different "team" if humans were doing it. *Example:* a sales-development rep books demos; a support rep handles complaints. Different agents.
**Don't** add an agent when:
- The work is just a short detour (use a flow or a tool call instead). *Example:* "look up the user's tier" doesn't need its own agent - it's one tool call.
- You only need to change tone for one topic (use Conversation Rules in your configuration).
- Splitting the work makes the conversation feel choppy to the user.
A common mistake: building five agents on day one. Start with just your configuration. Add an agent when you have a real reason - usually when you can name the task it owns ("books demos", "looks up order status") and explain why it shouldn't just be handled by the bot's default behaviour itself.
## Step 1: Create an agent
Go to **AI Agent → Agents**. Click **New agent**. The Create agent dialog asks for the bare minimum:
- A clear **name** that says what the agent does - `order-status-agent`, `demo-booking-agent`, `billing-agent`. This is the slug your routing rules and `@`-mentions will reference, so make it self-explanatory.
- An optional **Parent agent**. Leave this on `None - create a root agent` to make a top-level agent that routing can reach directly. Pick an existing agent to make this a [sub-agent](#sub-agents-hierarchical-children).
- An optional **Category** for grouping in the Agents list.
Click **Create**. The agent's profile page opens - that's where you'll fill in the rest.
## Step 2: Configure the agent's behaviour
The agent's profile has three sections, top to bottom:
- **Trigger** - a one- or two-sentence description of *when* this agent should take over. This is the agent's pitch to routing and the single most important field for routing. *Example:* "When the user asks about billing, invoices, refunds, payment-method changes, or charges." A sharp Trigger ("invoices, refunds, payment-method changes") leads to predictable routing; a vague one ("handles money stuff") doesn't. Keep it to *when* to fire - long Triggers with do/don't lists ("Trigger ONLY when… Do NOT trigger for… route to the KB instead") actually hurt matching. Push any "don't handle X" exclusions into a [Routing Logic rule](#step-3-make-the-handoff-explicit-optional-but-recommended) instead.
- **Lifecycle** - Setup flow, Tools, Rich Media, Sub-agents, Memory, Global memory. This is where the agent's actual behaviour lives. Each row is covered in the rest of this guide and the related pages.
- **Agent instructions** - the agent's identity, scope, and rules. A rich-text editor where you describe the persona and any do/don't constraints. *Example:* "You handle billing inquiries for Acme. You can look up invoices and process refunds, but never quote new pricing - let pricing questions be routed elsewhere." Write these in short, plain sentences with one action per line - see [Writing agent instructions](#writing-agent-instructions) below.
Keep **Trigger** for *when to take over*, and **Agent instructions** for *how to behave once you have the conversation*. Mixing them up - putting persona in the Trigger or routing hints in the Instructions - is the most common source of confused routing.
> **Note:** Every agent's profile shows two memory rows - **Memory** (local to that agent) and **Global memory** (bot-wide). They're a documentation/scope convention; at runtime both flow into a single shared pool keyed by `(botId, userId)`, so every agent can read each other's writes. See [Memory in Nexus agents](../configuration/memory.md) for the full model.
**Best practice:** keep agent identity tight. If the billing agent's identity tries to also handle shipping, you'll get unpredictable handoffs because routing now sees two agents that both look like good candidates for a shipping question.
### Writing agent instructions
The model follows clear, plain instructions far more reliably than emphatic ones. A few habits that pay off:
**Keep it simple and direct.** Short, plain-English steps beat a wall of capitalised emphasis. Shouting at the model doesn't make it comply - it just buries the actual instruction.
> **Bad:** "MANDATORY - DO NOT SKIP. You MUST collect the order ID and you must keep repeating until they get it right. THIS IS A CRITICAL STEP."
>
> **Good:**
> - Ask the user for their order ID and collect the response.
> - Call **@validateOrderId** with the response.
> - Valid → continue to the next step.
> - Invalid → ask again, then repeat.
**One instruction per sentence.** When you chain two actions with "and" or "then", the model often does the first and drops the second. Put each action on its own line.
> **Bad:** "Ask for the appointment date and confirm it back to the user and then book the slot."
>
> **Good:**
> - Ask the user for the appointment date.
> - Confirm the date back to the user.
> - Book the slot.
**Clean messy input before it reaches a tool.** People rarely answer in the exact shape a tool expects, so tell the agent how to normalise the reply before calling the tool. Pass a raw answer straight through and validation fails.
> **Bad:** User says "I'm based out of Mumbai, Maharashtra" → the agent passes the whole sentence to **@validateCity**, which rejects it.
>
> **Good:** "Extract only the city name - strip the state, country, and any filler - then call **@validateCity** with just the city."
### Sub-agents (hierarchical children)
In an agent's Lifecycle section you'll also see a **Sub-agents** row with an `+ Add sub-agent` button. Sub-agents are a different concept from the peer agents you create from the main **Agents** page:
| | Specialised agents (peers) | Sub-agents (hierarchical children) |
|---|---|---|
| **Created from** | `Agents` page → New agent (root) | Inside another agent's Lifecycle → `+ Add sub-agent`, or `New agent` with a Parent agent selected |
| **Who routes to them** | Top-level routing (driven by descriptions + Routing Logic) | Only their parent agent - they are hidden from the top-level router |
| **Use when** | The work is a distinct journey that should be considered for any incoming message (billing, order status, demo booking, …) | The work is a narrower step *inside* an agent's flow that benefits from its own persona, tools, or memory (e.g. a `refund-eligibility-check` sub-agent under the billing agent) |
For most bots you'll only need peer agents. Reach for sub-agents when one agent's flow has a self-contained sub-task that's complex enough to warrant its own identity, tools, or memory.
## Step 3: Make the handoff explicit (optional but recommended)
By default, routing uses each agent's **Trigger** (the textarea at the top of every agent's profile) to decide when to hand off. For simple bots with very distinct Triggers, that's enough - open the **Playground** (the ▶ icon in any agent's title bar) and send a test message; if the right agent picks it up, you're done. **You do not need any routing rules to ship.**
Reach for **Routing Logic rules** when you want a *deterministic* override on top of trigger-based routing. *Example:*
> "If the user mentions billing, invoices, refunds, or charges, hand off to the **@billing-agent**. Do not answer billing questions yourself."
A routing rule is harder than a Trigger - Triggers are signals routing weighs alongside the message, rules are explicit instructions ("always", "never") it must follow. Use rules when:
- Two agents have Triggers that overlap and routing isn't picking the one you want.
- A topic is sensitive enough that you don't want it answered by default behaviour at all (legal, regulated content, escalations).
- You need to express a compound condition the description can't capture ("If the user is in region X *and* asking about feature Y, route to…").
See [Routing Logic](../configuration/routing-logic.md) for the full guide on writing rules. See also [Routing Logic vs Start triggers](../configuration/routing-logic.md#routing-logic-vs-start-triggers) if you're wondering whether an agent's Start trigger could replace this step.
## Step 4: Add tools
Tools are the actions an agent can take in the real world: run a workflow, search a knowledge base, escalate to a human, transfer a call. You define them once in **AI Agent → Tools** and any agent in this bot can use them. Tools aren't required to live under an agent; a tool can be called directly if that's all the answer needs.
When you attach a tool to a specific agent, you're signalling "this tool belongs to this agent's job" - which is a useful routing hint. *Example:* attach the `getOrderStatus` workflow to the order-status agent, and routing learns to send order-tracking questions to that agent (with that tool available) instead of trying to answer with a different tool.
The four built-in tool types available today:
| Tool | What it does | Common use |
|---|---|---|
| **Workflow** | Connect to a workflow you built in the workflow editor. | Multi-step business logic, API integrations. *Example:* the `getOrderStatus` workflow inside an order-status agent. |
| **Knowledge Base** | Search documents and FAQs. | Product questions, policy lookup. *Example:* a returns-policy KB attached to the support agent. |
| **Escalate to Agent** | Route a chat to a human agent in Inbox. | Customer support escalation. *Example:* hand off when the user types "talk to a human". |
| **Transfer Call** | Forward a voice call to a human or SIP extension. | Voice escalation. |
More are coming (Connect MCP Server, HTTP Webhook, Custom Function, Slack/PostgreSQL/Google Calendar) - they appear in the picker today as "coming soon".
> **Guided agents are tools too.** A [guided agent](../guided-agents/index.md) is available as a tool to any conversational agent - call it when a conversation reaches a part that needs a fixed procedure (an order return, a KYC check), and it runs the deterministic flow and returns control. There's no separate "use agentic flows as tools" toggle to enable; guided agents are callable like any other tool.
The full guide for each lives under **[Tools - Overview](../tools/index.md)**:
- [Workflow tool](../tools/workflows.md) - connect a workflow as a tool.
- [Knowledge Base tool](../tools/knowledge-base.md) - answer from your docs and FAQs.
- [Escalation tools](../tools/escalation.md) - Escalate to Agent (chat) and Transfer Call (voice).
- [Tools best practices](../../best-practices/tools.md) - naming, descriptions, schemas, and routing.
## Step 5: Test the handoff
Open the **Playground** on any agent (▶ in the title bar) and send a message that should trigger your agent - e.g. "Can I get a refund?" for the billing agent. Watch:
- The **chat** - did the right agent's persona take over?
- Read the bot's response - did the right agent's persona take over on the first try? Did the right context carry over?
If the handoff didn't fire, two places to look: (1) sharpen the agent's **Trigger** - vague Triggers lead to fuzzy routing; (2) add or tighten a Routing Logic rule. If the handoff fired but the agent answered poorly, the issue is inside the agent - revisit its identity, rules, and tools.
> **Tip - manage tests from the Conversation Builder.** The Conversation Builder topbar exposes a **Tests** button. Open it to see linked test count, latest run summary, and live progress for any in-flight run. From there you can deep-link straight to the Testing Lab with this agent's tests pre-selected, or create a new test case pre-populated with this agent. See [Testing Lab → Manage tests from the Conversation Builder](../../test-debug/trust-centre/testing-lab.md#manage-tests-from-the-conversation-builder).
## `@`-mentioning vs handing off to an agent {#mentions-vs-handoff}
These two are easy to mix up - they look similar in the studio but do very different things. Understand the distinction once and you'll save yourself a lot of confusing routing bugs.
**`@`-mention** - In any markdown prompt field (bot identity, conversation rules, welcome and fallback messages, routing logic), type `@` to open a picker. You can mention four kinds of things: an **agent**, a **workflow**, a **tool**, or a **rich-media item**. The mention shows up as a colored chip whose label stays linked even if you rename the target - so your prompts don't go stale. Behind the scenes the chip stores the slug, not the name.
**A mention is a *reference*, not an action.** It puts the slug into the prompt as a semantic hint ("the user can ask the **@billing-agent** for refunds"). It does **not** trigger a handoff. What's mentioned may be *considered* when composing a reply, but a handoff only fires when something actually triggers routing.
**Agent handoff** - An agent only takes over the conversation when the conversation is **explicitly handed off** to it. Two things make a handoff fire:
1. A **Routing Logic rule** that names the agent (`"If the user asks about billing, hand off to the @billing-agent…"`).
2. A **Call agent / tool invocation** that targets the agent.
Once the handoff fires, the agent owns the conversation until it returns control.
### Side-by-side comparison
| | `@`-mention | Agent handoff |
|---|---|---|
| **Purpose** | Reference an agent / workflow / tool inline in prose. | Hand the conversation to a specialist. |
| **Where you set it** | Anywhere a markdown prompt editor accepts text (bot identity, rules, welcome, fallback, routing logic). | **AI Agent → Profile → Routing Logic** *or* a Call-agent / tool invocation. |
| **What's stored** | A markdown chip referencing the target's slug, e.g. `@[agent:billing-agent]`. | A first-class routing rule or tool config. |
| **Runtime effect** | None on its own - it's a hint that may be considered. | Hard handoff: the named agent takes over. |
| **What can be referenced** | Agents, workflows, tools, rich-media items. | Agents (or workflows / tools via dedicated tool types). |
| **Survives a rename?** | Yes - the chip resolves the live name from the slug. | Yes for tool / agent slugs; routing rules that hard-code names should also use `@`-mentions to stay current. |
### When to use which
| You want to… | Use |
|---|---|
| Make it known *that* a billing agent exists, so it can be mentioned in conversation. | `@`-mention inside bot identity. |
| Make sure billing questions *always* go to the billing agent. | Routing Logic rule (agent handoff). |
| Reference a workflow inside an instruction without binding the agent to call it. | `@`-mention. |
| Make the bot call a workflow when a condition fires. | Add it as a **Workflow** tool and reference from a routing rule. |
| Suggest a self-service path ("you can also visit our **@help-center** workflow") without forcing it. | `@`-mention. |
| Force escalation when the user asks for a human. | Routing Logic rule + Escalate-to-Agent tool. |
### A pattern that uses both
The strongest setup combines them:
> "If the user asks about billing, invoices, or refunds, hand off to the **@billing-agent**. Do not answer billing questions yourself."
The Routing Logic *rule* makes the handoff deterministic. The `@`-mention inside the rule keeps the agent's name resolved live - rename `billing-agent` to `billing-team` and the rule keeps working without an edit.
**Best practice:** in any rule, instruction, or message that names an agent, workflow, or tool, use `@`-mentions instead of typing the name as plain text. Plain text rots when slugs are renamed; chips don't.
## Best practices
- **Name agents by the task.** `order-status-agent`, `demo-booking-agent`, `billing-agent` beat `agent2`. The name shows up in routing rules and traces - make it self-explanatory.
- **Sharp descriptions beat clever rules.** A precise one-sentence description ("Handles billing: invoices, refunds, payment-method changes - does not quote new pricing.") routes correctly without any rule at all. Reach for rules only when descriptions can't disambiguate.
- **Don't double up.** If two agents have overlapping Triggers, you'll get inconsistent routing. Either merge them or sharpen the boundary.
- **Write instructions plain and one action per line.** Short steps beat capitalised "MANDATORY" walls, and chaining actions with "and"/"then" makes the model drop the second one. Tell the agent to clean messy replies (strip filler, extract the one field) before passing them to a tool. See [Writing agent instructions](#writing-agent-instructions).
- **Limit tool sprawl.** An agent with 20 tools is harder to predict than one with 4. If you find yourself adding many tools, consider whether some belong in a different agent.
- **Reuse with Global Components.** If multiple agents need the same policy text, brand voice, or disclaimer, define it as a Global Component and pull it in. One source of truth.
- **Document handoffs as you build.** Keep a short list: "Routing rule X sends Y type of question to Z agent." Future-you (or the next builder) will thank you.
- **Use `@`-mentions for any name that might be renamed.** The chip resolves to the current name; plain text doesn't.
Continue to: **[Best Practices](../../best-practices/agents.md)** or **[Test your agent](../../test-debug/index.md)**.
---
## Create an agent
Agents are the specialists that do the work in your bot. Nexus has **two types**, and the first thing you do when creating one is choose which: a **conversational agent** that reasons out each reply on its own, or a **guided agent** that runs a fixed flow you design. This page covers the **Create** picker, how to choose, and where to go next for each type.
Both types share the same **Agents** page and the same **Create** entry point - they only diverge once you pick. (Whichever you build, the bot-wide [Configuration](../configuration/index.md) still applies to it; Configuration is project-level and shapes every agent.)
Don't want to start from scratch? Ask the [Nexus AI Layer](../../ai-layer/index.md) to scaffold an agent from a one-line description - it picks a sensible type, lays out the first steps, and waits for you to refine.
## Step 1: Open the Agents page
In your bot, go to **AI Agent → Agents**. The page header reads **Agents**, with **What's new**, **Publish**, and **Create** in the top-right. Below the header are two tabs:
- **Conversational (N)** - your LLM-driven agents (prompt + trigger, Live/Draft status, round avatar).
- **Guided (N)** - your guided agents (flow icon, a Category tag, no status).
The active tab is saved in the URL (`?tab=guided`), so a link you share reopens on the same tab.
## Step 2: Click Create and choose a type
Click **Create** in the top-right. The **"What would you like to create?"** picker opens with two options:
| Option | Studio description |
|---|---|
| **Conversational agent** | "Understands the question, asks for anything it's missing, and works out each reply on its own from your knowledge. Great for use cases like troubleshooting and support - diagnosing errors, fixing login and device issues, or guiding people to a resolution, step by step." |
| **Guided agent** | "Runs the exact steps you design, in the same order every time, so nothing is missed and every run stays consistent and auditable. Great for multi-step use cases like order returns, loan applications, KYC checks, or booking an appointment." |
### Which one should I pick?
| You want… | Build a… |
|---|---|
| Open-ended help where each reply is reasoned from your knowledge - troubleshooting, support, diagnosing errors, free-form Q&A | **Conversational agent** |
| A fixed sequence of steps that runs identically every time and stays auditable - returns, KYC, loan applications, bookings | **Guided agent** |
| Mostly open-ended help, but with one procedure that must run the same way every time | **Conversational agent** that calls a guided agent as a tool |
| A deterministic flow with one or two steps that need open-ended reasoning | **Guided agent** with a [Conversational Agent node](../guided-agents/agent-node.md) inside it |
> **Tip - you can mix both.** A guided agent can include **Conversational Agent nodes** for the steps that genuinely need open-ended reasoning, while the flow keeps the overall sequence deterministic. And every guided agent is automatically available as a **tool** to your conversational agents - so a conversational agent can pull a deterministic journey into an otherwise open-ended conversation. You rarely have to pick one type forever.
## Step 3: Name your agent
Whichever type you chose, give the agent a clear, task-based name that says what it *does* - `order-status`, `billing`, `order-return`, `kyc-verification`. The name is the slug your routing rules, `@`-mentions, and other agents will reference (a conversational agent calls a guided agent by this name when it uses it as a tool), so make it self-explanatory.
**Naming tips:**
- **Name the job, not the topic.** `order-return` beats `returns-stuff`; `loan-application` beats `loans`.
- **Use the same casing as your other agents** so the list stays scannable.
- **Avoid duplicate names** - each agent needs a distinct name.
## Step 4: Continue based on the type you chose
The two types diverge from here:
- **Conversational agent** → you land on the agent's profile, where you write its **Trigger**, **Agent instructions**, and attach tools. Continue to **[Conversational agents](conversational-agents.md)**.
- **Guided agent** → you land on the **flow canvas**, where you add nodes and wire them into a flow. Continue to **[Guided agents overview](../guided-agents/index.md)** and then **[The guided flow canvas](../guided-agents/flow-canvas.md)**.
> **Note:** The two types share the **Agents** page but are separate entities under the hood. A guided agent has **no Live/Draft status** - a flow has no draft lifecycle - and it shows a generated flow icon instead of an avatar. For the full distinction, see [Guided agents overview](../guided-agents/index.md).
---
## Build by use case
You know what you want the bot to *do* - the question is which kind of agent to build. Nexus has [two types](create.md): a **conversational agent** that reasons out each reply on its own from your instructions and knowledge, and a **guided agent** that runs a fixed flow you design, the same way every time. This page is a jobs-to-be-done router: find the scenario closest to yours, see which type fits and why, and jump straight to the build path.
> **Not sure which fits?** Start at **[Create an agent](create.md)** - it walks through the Create picker and the conversational-vs-guided choice in one place. The rule of thumb: if you'd describe the work as *"it depends on what they ask,"* build a conversational agent; if you'd describe it as *"first this, then this, then this - every time,"* build a guided agent.
## What are you building?
| Goal | Best fit | Why | Start here |
|---|---|---|---|
| **Open-ended support / FAQ** - answer questions, troubleshoot, diagnose, guide to a resolution | **Conversational** | The path depends on what the user says; the agent works out each reply from your knowledge and adapts turn by turn. | [Conversational agents](conversational-agents.md) + [Knowledge base](../tools/knowledge-base.md) |
| **Order tracking / status lookups** - fetch a record and report back ("where's my order?") | **Conversational** + a workflow tool | Still open-ended (users phrase it many ways), but the lookup itself must hit a system of record - so attach a workflow that does the fetch. | [Conversational agents](conversational-agents.md) + [Tools](../tools/index.md) |
| **Appointment booking / KYC / returns** - a fixed multi-step procedure that must run identically every time | **Guided** | The steps and their order are fixed; you want every run consistent and auditable, with no step skipped or reordered. | [Guided agents](../guided-agents/index.md) |
| **Lead qualification** - gather details and score/route a prospect | **Conversational** (or **Guided** if scripted) | If the questions adapt to the answers, conversational. If sales mandates the exact questions in the exact order, make it a guided flow. | [Conversational agents](conversational-agents.md) · [Guided agents](../guided-agents/index.md) |
| **Voice agent** - handle the same job over a phone call | **Either** | Type is independent of channel - a conversational *or* guided agent can run on voice. Pick the type by the job above, then enable voice. | [Voice on Nexus](../../voice/index.md) |
## The scenarios in detail
### Open-ended support / FAQ
Reach for a **conversational agent**. There's no fixed path to enforce - the agent understands the question, asks for anything it's missing, and reasons out each reply from your knowledge. Give it a [Knowledge base](../tools/knowledge-base.md) tool so its answers stay grounded in your content, and write a clear trigger and instructions on the [conversational agent](conversational-agents.md) profile.
### Order tracking / status lookups
Also a **conversational agent**, because users ask in a hundred different ways - but the answer has to come from a system of record, not from the model. Attach a **workflow** tool that does the lookup (an API call keyed by order ID, account number, or ticket reference) and the agent calls it when it has what it needs. See [Tools](../tools/index.md) for how workflows plug into an agent, and the [conversational agent](conversational-agents.md) page for wiring the tool to a trigger.
### Appointment booking / KYC / returns (fixed multi-step)
Build a **guided agent**. These are regulated or procedural journeys where skipping or reordering a step is unacceptable - collect details, check eligibility, confirm, then act. A guided agent draws the path explicitly on a canvas, so every run is consistent and auditable. Start at [Guided agents](../guided-agents/index.md); a step that genuinely needs open-ended reasoning can still be a Conversational Agent node *inside* the flow.
### Lead qualification
This one goes either way. If the conversation should adapt - probing deeper when a prospect sounds qualified, moving on when they don't - build a **conversational agent** and let it reason. If your sales process mandates the *exact* questions in the *exact* order (for scoring parity or compliance), build a **guided agent** so every lead is qualified identically. See [Conversational agents](conversational-agents.md) and [Guided agents](../guided-agents/index.md).
### Voice agent
Agent **type is independent of channel**. The same conversational or guided agent you'd build for chat can run a phone call - so choose the type by the job (use the rows above), then turn on voice. Start at [Voice on Nexus](../../voice/index.md) for the runtime modes, voice library, and testing.
Describe your use case to the [Nexus AI Layer](../../ai-layer/index.md) and it'll suggest a type and scaffold the first steps - then refine from there.
> **Tip - you can mix both.** A conversational agent can call a guided agent as a tool when a conversation reaches a part that needs a fixed procedure (for example, a support agent that hands off to a `kyc-verification` guided agent). And a guided agent can include Conversational Agent nodes for the steps that need open-ended reasoning. You rarely have to pick one type forever.
## Read next
- **[Create an agent](create.md)** - the Create picker and the type choice, end to end.
- **[Conversational agents](conversational-agents.md)** - triggers, instructions, and attaching tools.
- **[Guided agents](../guided-agents/index.md)** - the flow canvas, nodes, and exit branches.
- **[Tools](../tools/index.md)** - workflows, knowledge base, escalation, and more.
---
## AI safety & conduct
**AI safety & conduct** is where you set the content-moderation guardrails that apply to every agent in your project - conversational and guided alike. These filters inspect what users send in and what your bot sends back, blocking unsafe content before it reaches a person. Because **Configuration** is project-level, whatever you enable here protects the whole bot, not a single agent.
This page is part of **Configuration**. Settings here apply to all your [agents](../agents/conversational-agents.md) and [guided agents](../guided-agents/index.md). For an overview of how Configuration fits together, see [Configuration](index.md) and the [Harness overview](../index.md).
> **Note:** The AI safety & conduct sub-page only appears if it's enabled for your account. If you don't see it under **Others** in the left menu, your project doesn't have safety filters provisioned - talk to your account team.
## Step 1: Open the AI safety & conduct page
In your bot, go to **AI Agent → Configuration** and click **AI safety & conduct** (under **Others** in the left menu).
The page splits filters into a foundational, always-on layer and an advanced layer you toggle per check:
- **Standard content safety** - a foundational, always-on content-moderation check. It runs by default and can't be turned off.
- **Customer query filters** (advanced) - individual checks on what the user sends *in*: toggle **Banned Topics**, **Violence**, **Sexual content**, and similar to block unsafe inputs before the bot acts on them.
- **AI response filters** (advanced) - individual checks on what the bot sends *back*: **Toxicity**, **Bias**, and **Sensitivity** (sensitive-data leakage) in the generated reply.
## Step 2: Choose your advanced filters
**Standard content safety** is on for everyone - you don't configure it. Decide which **advanced** checks you need on top of it:
| Layer | Filter | Catches |
|---|---|---|
| Customer query filters | **Banned Topics** | User messages about topics you've ruled out of scope. |
| Customer query filters | **Violence** | Violent or harmful user inputs. |
| Customer query filters | **Sexual content** | Sexually explicit user inputs. |
| AI response filters | **Toxicity** | Hostile, abusive, or offensive wording in the bot's reply. |
| AI response filters | **Bias** | Biased or discriminatory framing in the bot's reply. |
| AI response filters | **Sensitivity** | Sensitive-data leakage in the bot's reply. |
Turn on a filter by toggling it. Query filters guard the **input** path; response filters guard the **output** path - most regulated use-cases want coverage on both sides.
## Step 3: Mind the latency trade-off
Every advanced filter you enable adds a moderation pass, and each pass costs time.
> **Note:** The page warns: *"Enabling filters adds latency. For time-sensitive use-cases like VoiceAI agents, consider disabling them."* For voice channels, weigh filter coverage against your turn-latency budget - a moderation pass that's invisible on chat can become an audible pause on a call.
> **Tip - voice vs chat.** If the same project serves both chat and voice, decide which layers are non-negotiable for compliance and keep only those on for voice. You can run a fuller filter set on chat where the extra latency doesn't hurt the experience.
Not sure which checks your industry needs? Ask the [Nexus AI Layer](../../ai-layer/index.md) to recommend a filter set for your use-case, then tune it against the latency budget for your channels.
## Best practices
- **Turn safety filters on _before_ you ship**, not after a customer hits one. A filter that blocks unsafe content in production is worth far more than one you added in a post-incident review.
- **Test adversarial prompts** in the [Testing Lab](../../test-debug/index.md) before each release. Send the kinds of inputs you most want blocked (banned topics, hostile language, attempts to extract sensitive data) and confirm the filter catches them.
- **Pair filters with safe landings.** For regulated industries (finance, healthcare), back these checks with legal-approved [fallback](fallback.md) messages so a blocked turn has somewhere safe to land instead of a generic error.
- **Cover both directions for high-stakes bots.** Query filters stop unsafe inputs; response filters stop unsafe outputs. For anything handling regulated or personal data, enable both.
- **Re-measure latency after each change.** Enabling a filter shifts your latency profile - especially on voice. Re-test turn timing whenever you add or remove a check.
---
**Next:** [Voice settings](voice-settings.md)
---
## Conversation rules
**Conversation rules** are persona-level guidelines - *always do* and *never do* - that are applied to every reply your bot sends. Because they live in [Configuration](index.md), they are **project-level**: every agent in the bot follows them, whether it's a [conversational agent](../agents/conversational-agents.md) answering open-ended questions or a [guided agent](../guided-agents/index.md) running a fixed flow.
Think of them as the house rules the whole team works by. The [bot identity](profile.md) says who the bot is; conversation rules say what the bot always does and never does, no matter which agent is replying.
> **Per-node opt-out.** A [Conversational Agent node](../guided-agents/agent-node.md#conversation-rules) inside a guided flow can opt out of these global rules with its **Apply global conversation rules** toggle - useful for a tightly scripted step whose exact wording the general rules would interfere with. The rules still apply everywhere else.
Not sure where to start? Ask the [Nexus AI Layer](../../ai-layer/index.md) to suggest a starter set of conversation rules from a one-line description of your bot, then trim and reword them to fit.
## Step 1: Open Conversation rules
In your bot, click **AI Agent → Configuration**, then open **Conversation rules** (under **General** in the left menu).
Rules are numbered and capped at **30 per bot**. The header shows how many you've used (for example, *3 / 30 rules*). Click **Edit** to add, reword, or remove rules.
## Step 2: Write your rules
Each rule is a single, plain-language instruction. Add one rule per line and keep each one to a single concern.
Examples:
| Rule | What it does |
|---|---|
| "Always confirm the user's order ID before sharing shipment details." | Guards against leaking the wrong order's data. |
| "Never share another customer's information, even if asked." | A hard safety boundary that holds across every agent. |
| "If the user expresses frustration, acknowledge it before continuing." | Shapes tone on difficult turns. |
> **Note:** Conversation rules apply to *every* reply. If a behaviour should only happen inside one agent or one flow, put it in that agent's instructions or [guided-agent steps](../guided-agents/index.md) instead - not here.
## The 30-rule cap
A bot can hold at most **30** conversation rules. The cap is deliberate: the more rules you stack, the more likely two of them quietly contradict each other, and the harder it is to predict which one wins. If you're brushing up against 30, that's usually a sign that some rules belong inside a specific agent's instructions rather than in the project-wide list.
## Best practices
- **One rule = one concern.** Don't combine "always confirm order ID and never share other customers' info" into one line; split them into two rules.
- **Phrase rules positively when you can.** "Confirm the order ID" beats "don't proceed without an order ID" - positive instructions are easier for the model to follow.
- **State the hard "never do" rules explicitly.** Safety and compliance boundaries ("never share another customer's data") belong here so they apply to every agent, every turn.
- **Re-read your list after writing.** If two rules contradict, the bot's behaviour will too. Conflicting rules are the most common cause of inconsistent replies.
- **Keep it lean.** Treat the 30-rule cap as a guide, not a target - a short, clear list beats a long, tangled one.
> **Tip - test before you ship.** After editing rules, open the **Playground** (the play ▶ icon on any agent) and send messages that should trigger each rule. If a reply ignores a rule, check whether another rule or the [bot identity](profile.md) is pulling the other way. See [Testing & debugging](../../test-debug/index.md) for the full loop.
## Next
With your conversation rules in place, set up how the bot picks an agent or tool for each message: **[Routing logic](routing-logic.md)**.
---
## Fallback
**Fallback** controls what your bot does when it can't handle a request - a question that's clearly out of scope, gibberish it can't parse, or input that fails validation one too many times. Because fallback lives under **Configuration**, it's a project-level setting: the recovery behaviour you define here applies to **all** your agents, both [conversational](../agents/conversational-agents.md) and [guided](../guided-agents/index.md).
A good fallback turns a dead end into a next step. A bad one - the default apology string - leaves the customer stuck and reaching for a human.
## Step 1: Open the Fallback page
In your bot, click **AI Agent → Configuration**, then open **Fallback** (under **Agents** in the left menu).
This sub-page has two controls:
- **Next steps after failure** - how the bot recovers when it can't answer.
- **Retries for information validation failures** - how many times to re-ask when a user's input doesn't validate.
## Step 2: Write the fallback instruction (Instruct mode)
In Nexus, fallback uses **Instruct** - a prompt fragment you write that defines *how to recover* when a request can't be handled. Instead of returning a fixed apology, the bot uses your instruction to compose a helpful, in-context response that offers the user a real way forward.
Write the instruction the way you'd brief a support agent on what to do when they're stuck:
```
You couldn't handle the user's request. Apologise briefly, then offer
concrete next steps: ask them to rephrase, point them to the FAQ, or offer
to connect them to a human via the Escalate-to-Agent tool. Never invent an
answer. Keep it to two short sentences.
```
> **Tip - `@`-mentions.** Type `@` in the Instructions editor to insert a live reference to an agent, workflow, or tool - for example `@escalate-to-agent` so the model knows exactly how to hand off. The chip stays linked to the target's slug, so it won't break if the target is renamed.
## Step 3: Set retries for validation failures
Below the instruction, set **Retries for information validation failures** - how many times the bot re-asks the user when their input doesn't pass validation (for example, an order ID in the wrong format, or an unparseable date). The default is **3**.
Once the retry budget is exhausted, the bot stops re-prompting and falls back to the **Instruct** behaviour above - so the two controls work together: retries handle the *recoverable* case (the user just needs to try again), and the instruction handles the *give-up gracefully* case.
> **What the fallback reply can read.** When no sub-agent is active, the fallback/root-responder composes the reply. Its read scope follows the super agent's [**Allowed variables**](memory.md#allowed-variables-per-agent-read-scope): set an allowlist there to keep the fallback prompt scoped to just the variables it needs.
| Control | What it does | Default |
|---|---|---|
| **Next steps after failure (Instruct)** | Prompt that defines how the bot recovers when it can't handle a request | - |
| **Retries for information validation failures** | How many times to re-ask when input doesn't validate before falling back | 3 |
## Best practices
- **Don't leave fallback as the default apology string.** Use the instruction to offer concrete next steps - rephrase the question, browse FAQs, or escalate to a human via the [Escalate-to-Agent tool](../tools/index.md).
- **Always give the customer somewhere to land.** Pair the instruction with an explicit handoff path so a stuck user is never left at a dead end. This matters most in regulated industries (finance, healthcare), where the safe fallback is often a human.
- **Keep retries low.** Re-asking more than 3 times reads as nagging; if a user can't pass validation after a few tries, falling back to a human is usually kinder than another retry.
- **Test it.** Send obvious gibberish and questions clearly outside scope to confirm the fallback fires the way you expect. Run these checks in the [Testing Lab](../../test-debug/index.md) before each release.
Not sure how to phrase the recovery? Ask the [Nexus AI Layer](../../ai-layer/index.md) to draft your fallback instruction from a one-line description of what should happen when the bot gets stuck.
---
**Next:** [Conversation rules](conversation-rules.md) - the *always do* / *never do* guidelines applied to every reply.
---
## Configuration
**Configuration** is project-level. The settings you define here apply to **all your agents** - every [conversational agent](../agents/conversational-agents.md) and every [guided agent](../guided-agents/index.md) in the bot inherits them. It is where you set the behaviour that shapes every conversation: persona and identity, conversation rules, routing logic, memory, fallback, lifecycle hooks, AI safety, and voice.
Every incoming message is read and routed to the right place - answered directly, handed off to one of your conversational agents, reached through a guided agent, or resolved with a [tool](../tools/index.md) - and the response is shaped by these project-level settings. Configuring them well is the single highest-leverage thing you can do for your bot's quality.
This page is the map of the **Configuration** category. Each section below has its own sub-page; the order shown is the one we recommend you fill them out in.
> **Note:** If you came from the legacy platform, you'll find the same fields here with a few additions for Nexus.
Stuck on the wording? Ask Nexus to draft your bot identity from a one-line description, then refine it. It can also tighten an existing identity or add a "never do" rule for you.
## Open the Configuration page
In your bot, click **AI Agent → Configuration**. The page has a left menu grouped into three sections:
- **General**
- Profile settings
- Conversation rules
- **Agents**
- Routing logic
- Memory
- Lifecycle hooks
- Fallback
- **Others**
- AI safety & conduct *(if enabled for your account)*
- Voice settings
Start at **Profile settings** and work down the list.
## What each section does
| Section | What it controls | Sub-page |
|---|---|---|
| **Profile** | Persona, bot identity, and welcome message - who your bot is and how it greets users. | [Profile](profile.md) |
| **Conversation rules** | Persona-level *always do* / *never do* guidelines applied to every reply (max 30). | [Conversation rules](conversation-rules.md) |
| **Routing Logic** | Optional plain-English rules that override or refine how each message is routed between agents and tools. | [Routing Logic](routing-logic.md) |
| **Memory** | Variables shared by all agents across conversations - `customer_id`, `account_tier`, and similar shared context. | [Memory](memory.md) |
| **Fallback** | What the bot does when it can't handle a request, plus retry behaviour for failed input validation. | [Fallback](fallback.md) |
| **Lifecycle hooks** | Optional cross-cutting behaviour - on session start and on inactivity - for nudges, logging, and context injection. | [Lifecycle hooks](lifecycle-hooks.md) |
| **AI safety & conduct** | Content-safety filters on user inputs and bot responses *(if enabled for your account)*. | [AI safety & conduct](ai-safety.md) |
| **Voice settings** | TTS provider and voice, voice instructions, and VAD tuning for voice channels. | [Voice settings](voice-settings.md) |
> **Tip -** You don't have to fill in every section. **Profile** is the only one most bots can't skip; **Routing Logic**, **Lifecycle hooks**, and **Voice settings** are optional and only matter when your use case needs them.
## Save and test
After editing any section, click **Save**. Then go to **AI Agent → Agents**, click the **play (▶)** icon on any agent to open the **Playground**, and send a few test messages. Read each response to confirm the bot is behaving as you intended. For deeper checks - adversarial prompts, regression suites - use the [Testing Lab](../../test-debug/index.md).
If something looks off, it's almost always one of:
- Bot identity too vague → tighten it in [Profile](profile.md).
- Conversation rules contradict → simplify them in [Conversation rules](conversation-rules.md).
- Routing is sending messages to the wrong place → add a rule in [Routing Logic](routing-logic.md).
---
**Next:** [Profile](profile.md) - pick a persona, write the bot identity, and set the welcome message.
---
## Lifecycle hooks
**Lifecycle hooks** let you run cross-cutting behaviour at key moments in a conversation - at the start of a session, or when a user goes quiet. Because Lifecycle hooks live in **Configuration**, they are **project-level**: they apply across the bot, regardless of which agent ([conversational](../agents/conversational-agents.md) or [guided](../guided-agents/index.md)) happens to be handling the turn.
Most bots don't need any hooks. Reach for them when you want behaviour that isn't tied to a single reply - analytics, custom logging, dynamic context injection, or proactive nudges when a user stalls.
> **Note:** Hooks are optional. Leaving them all off is a perfectly valid configuration - skip this page until you have a concrete cross-cutting need.
## Step 1: Open Lifecycle hooks
In your bot, open **AI Agent → Configuration**, then select **Lifecycle hooks** (under **Agents** in the left menu).
The sub-page lists the available hooks. Each hook has an **active toggle** and an **expand arrow** to configure its rules and actions. A hook does nothing until you toggle it on and configure it.
Two hook types are available today:
| Hook | Fires when | Typical use |
|---|---|---|
| **On session start** | The user sends the first message and a new session begins. | One-time setup at the start of a conversation. |
| **On inactivity** | The user has been idle for a configurable duration. | Proactive nudges to re-engage a stalled user. |
## Step 2: On session start
The **On session start** hook fires once, when a user sends their first message and a new session begins. Use it for one-time setup at the start of a conversation:
- Pre-load context (look up the customer, set [Memory](memory.md) variables).
- Log the session for analytics.
- Run an onboarding workflow before the first reply.
Toggle the hook on, expand it, and attach the workflow or action you want to run on session start.
## Step 3: On inactivity
The **On inactivity** hook fires after the user has been idle for a configurable duration. It is **rules-based**: you add up to **5 rules per agent**, each with:
- A **threshold** - the idle duration before the rule fires (up to **59 minutes**).
- A single **workflow action** - the workflow that runs when the threshold trips.
The workflow runs **without an LLM round-trip** - it's a deterministic nudge, so it's fast and predictable.
### How it works
- Each inbound user message **resets the timers**.
- When a threshold elapses without a new user message, the matching rule fires its workflow.
- If multiple rules elapse at once (caused by a backend lag, say), only the **largest-eligible threshold** fires - so customers don't get a stack of stale nudges all at once.
### Customer Support preset
A **Customer Support preset** ships an out-of-the-box ladder you can drop in as a starting point:
| Threshold | Intent |
|---|---|
| 60 s | Gentle nudge - "Are you still there?" |
| 180 s | Stronger nudge |
| 300 s | Hand-off |
> **Note:** The preset is visible **only in the empty state**, so you can't accidentally clobber rules you've already authored. Once you add your own rules, the preset is no longer offered.
### When to reach for it
- **Customer support:** re-engage idle users with "Are you still there?", then offer human handoff.
- **Sales / booking:** send an abandoned-cart-style nudge when a user stalls mid-form.
- **Long-running flows:** capture lead data before the session times out.
Not sure how to word the nudge? Ask the [Nexus AI Layer](../../ai-layer/index.md) to draft a short, friendly re-engagement workflow message for you, then refine the threshold ladder to fit your channel.
## Best practices
- **Keep thresholds short → long** (60 s → 5 min). Stacking three nudges in quick succession reads as harassment.
- **Start from the CS preset** and tune the workflow contents to your tone and channel.
- **Handle the missing-context case** in the inactivity workflow - by the time it runs, the user may have left, so don't assume earlier session state is still meaningful.
- **Don't over-hook.** If a behaviour belongs to one agent's flow, put it in a [tool](../tools/index.md) or the agent itself rather than a project-level hook.
Once you've configured (or skipped) your hooks, validate them by sending a first message and then letting a session sit idle in the [Testing Lab](../../test-debug/index.md).
---
**Next:** [Fallback](fallback.md)
---
## Memory in Nexus agents
Memory is how your Nexus bot retains context about the customer across turns - and across switches between your **conversational agents** (the LLM-driven specialists). This page covers what memory **is**, what it **isn't**, and the difference between an agent's local **Memory** and the bot-wide **Global memory**.
## Memory ≠ Variables
If you only need to pass a value into an attached tool or workflow, **you don't need memory**. The tool will pick the value up directly from its input mapping at execution time.
Use memory only when you want to **intentionally retain context about the customer / end-user** so a later turn (or a different agent) can read it.
```
Tool input mapping → for data flow between a turn and a tool call
Memory → for context you want to remember across turns
```
## Memory vs Global memory
Your Nexus bot declares memory in two places, both backed by the same runtime store:
- **Configuration → Memory** (under **Agents** in the Configuration nav) - variables that are *shared across every agent in the bot*. The page calls them "memory variables accessible to all agents across conversations". These same variables appear on every specialised agent's profile as the **Global memory** row.
- **Each specialised agent's Memory row** (in its Lifecycle section) - variables that are *local to that one agent*.
So on a single agent's profile you see **two memory rows side by side**: **Memory** (this agent's local vars) and **Global memory** (the bot-wide vars defined on the Configuration → Memory page).
Both surfaces use the same entry fields:
| Field | Required | Notes |
|---|---|---|
| Variable name | ✅ | Letters, digits, underscores. Must start with a letter or underscore. |
| Data type | ✅ | `string`, `number`, `boolean`, `object`, `array`. |
| Default value | - | Seeded into memory when the conversation starts. |
| Description | ✅ | What the variable means and when to use it. Helps the model decide whether to write to it. |
Use **Memory** for context only this agent's flow needs to track (`bike_model_picked`, `preferred_test_ride_slot`). Use **Global memory** for context every agent should be able to read and write (`customer_id`, `account_tier`, `preferred_language`).
Variable names in **Memory** are validated against **Global memory** to prevent duplicates within the same agent's view.
## How memory actually behaves at runtime
**This is the part most people get wrong.** At runtime, an agent's **Memory** and the bot's **Global memory** flow into **the same memory store** - a key-value pool scoped to `(botId, userId)`, persisted for **2 days**. The Memory / Global memory split is a *declaration* convention that documents intent and scopes the UI; it is not a runtime isolation boundary.
In practice:
- **Memory survives agent handoffs.** If the billing agent writes `last_invoice_id`, the support agent can read it on the next turn.
- **Memory survives short breaks.** If the customer comes back within 2 days, prior memory is still there.
- **Memory is per customer, per bot.** Two different customers talking to the same bot have independent memory.
:::caution
**Pick variable names with this in mind.** Because every agent in the conversation can see every other agent's writes, name collisions across agents will silently overwrite each other. Prefix or namespace agent-local variables (`billing_last_invoice_id`) when there's any chance of overlap.
:::
## Allowed variables (per-agent read scope)
By default an agent can read the whole memory pool plus the caller's user properties. **Allowed variables** lets you narrow that down: pick an explicit list of variables and user properties, and the agent may **read** only those.
You'll find it on **AI Agent → Configuration → Profile settings**, in the **Allowed variables** section (available when the bot uses unified memory). It's a chip picker over your **Global memory** variables and **user properties**, with its own **Save**. The helper text reads *"This agent can only read the variables and user properties you add here."* Add `*` to allow **all** user properties.
- **Leave it empty** and nothing is restricted — the agent reads memory and user properties as before. The allowlist only takes effect once you add at least one entry.
- Allowed variables scopes **reads only**. It doesn't change what the agent can write.
:::tip Scope the super agent's routing and fallback
Set **Allowed variables** on the **super agent** (the router) to control what the routing decision and the fallback / root-responder reply are allowed to read. With an allowlist set, the router's Context Expert prompt and the no-active-sub-agent fallback reply see **only** those variables — not the entire user profile and every global. Use it to keep routing focused and to keep PII out of prompts that don't need it.
:::
## Sharing parent memory with sub-agents (opt-in)
For tightly-coupled parent / sub-agent pairs you can *opt in* to projecting a parent agent's agent-scoped Memory into its sub-agents' prompt context - without using Global memory and without inlining values into Trigger instructions.
How it works:
- Set `exposeMemoryToSubAgents: true` on the parent agent's compiled config.
- When a sub-agent runs, the parent's Memory keys appear in the sub-agent's `` under a `parentAgent` section, with each key rewritten as `parent.`.
- The projection is **read-only**: the sub-agent sees the values but cannot write to the parent's scope through this surface. The existing merge-on-pop behaviour (where a child's local vars merge back into the parent on completion) is unchanged.
The `parent.` prefix prevents collisions - a child's own `customer_id` and the parent's `parent.customer_id` are distinct keys the LLM can address separately.
**When to use it**
- A sub-agent needs to read state the parent already collected (verified identity, order context) without that state leaking to peer specialised agents via Global memory.
- The parent / sub-agent pair is a tightly-scoped delegation and you don't want to namespace-pollute by writing to Global.
**When not to**
- The value is needed by *multiple* root agents - that's what Global memory is for.
- You want the sub-agent to be able to *write back* to a shared key - there's no write path through this surface; use Global memory or rely on the merge-on-pop behaviour.
> **Today this is a runtime-only flag.** The agent profile editor doesn't expose a toggle yet - the runtime accepts `exposeMemoryToSubAgents` as soon as the platform sends it, but you'll need platform-side configuration or a future builder UX to enable it. A builder UI for this is a planned follow-up.
## Best practices
- **Declare what you depend on.** If an agent reads `customer_tier`, declare it - even if another agent writes it. Declarations are the only documentation the next person editing your bot has.
- **Reference declared memory in prompts; don't improvise variables.** Before writing an **Agent instructions** prompt, map the Global memory (Configuration → Memory) the agent will read and write, and reference those names. A conversational agent's prompt should point at declared memory rather than inventing an ad-hoc variable mid-prompt that nothing seeds or persists. (Flow-local variables inside a **guided flow** are different - those are scoped to the flow and don't need to live in Global memory.)
- **Name variables for what they store.** `user_details`, `delivery_full_address`, `name_on_order` tell the next editor - and the model - what's inside. `data1`, `temp`, `data_temp2` tell them nothing and make collisions harder to spot.
- **Use workflow-returned values as-is.** When a tool or workflow returns a value, store and reuse it verbatim - don't ask the model to reformat or "correct" it, or you get silent corruption.
> **Bad:** prompt the model to re-title-case the city a lookup returned. **Good:** store `result.normalized_city` (the value the workflow already normalised) and treat it as canonical.
- **Default values matter.** Without a default, the variable is `undefined` until something writes to it, and downstream tools may get an empty payload.
- **Don't use memory as a scratchpad.** Memory persists for 2 days. If a value only matters within a single turn, pass it through tool input mapping instead.
- **Don't put secrets in memory.** Memory is conversation-scoped, not session-encrypted. Tokens and credentials belong in tool configuration, not in memory.
---
## Profile
**Profile** is the first sub-page under **AI Agent → Configuration → General**, and it's where you set who your bot is and how it greets people. Because [Configuration](index.md) is project-level, everything you set here applies to **all** your agents - both [conversational agents](../agents/conversational-agents.md) and [guided agents](../guided-agents/index.md). Get the profile right and every reply, from any agent, inherits the same persona and identity.
This page covers three things, in the order we recommend filling them out:
1. **Pick a persona** - set the tone with a preset.
2. **Write the bot identity** - the system instruction that defines who the bot is.
3. **Set the welcome message** - how the first turn of every conversation begins.
To open it, go to **AI Agent → Configuration** in your bot and click **Profile settings** in the left menu.
Stuck on the wording? Ask the [Nexus AI Layer](../../ai-layer/index.md) to draft your bot identity from a one-line description, then refine it. It can also tighten an existing identity or add a "never do" rule for you.
## Step 1: Pick a persona
Choose one of the available presets - for example *Polite and persuasive*, *Empathetic and helpful*, or *Witty*. The persona is a quick way to set tone without writing prompt text yourself.
**Best practices**
- Pick **one** persona and let your bot identity (next step) carry the nuance. Mixing presets in your head ("I want it warm but witty") usually leads to a less coherent voice.
- Match persona to channel. Voice flows benefit from *Empathetic and helpful*; sales pages often want *Polite and persuasive*.
## Write the bot identity
This is the most important field on the page. **Bot identity** is the system instruction that tells your bot who it is, what it does, and what it must not do.
Write it as if you were briefing a new hire on day one:
```
You are Aria, the support assistant for Acme Logistics. You help customers
track shipments, file claims, and update delivery preferences. You never
quote pricing - that's handled by the sales team. If a customer asks about
pricing, route them to the @sales-agent. Use a calm, professional tone.
Do not make up tracking numbers under any circumstance.
```
**Best practices**
- **Lead with the role**, then the responsibilities, then the constraints, then the tone. The model pays the most attention to your first lines.
- **Be concrete.** "You help customers" is too vague; "You help customers track shipments and file claims" is testable.
- **State what the bot must NOT do**, not just what it should do. The "never quote pricing" instruction in the example above is what stops bad behavior.
- **Don't write marketing copy here.** This is an instruction to a model, not a brand brochure.
> **Tip - `@`-mentions.** Type `@` in this field (or any prompt field) to insert a live reference to an agent, workflow, or tool. The chip stays linked to the target's slug, so it doesn't break when the target is renamed. Mentioning is a *hint* to routing - it does **not** trigger a handoff. To make an agent actually take over, use a [Routing Logic](routing-logic.md) rule.
## Step 3: Set the welcome message
Still on **Profile settings**, scroll to the **Choose how to welcome** section. Click **Change** to open the picker - Nexus shows three kinds of options:
| Option | Studio label | When to use |
|---|---|---|
| **Instruction** | *Instruct super agent* | Generate a greeting from a prompt fragment you write. Good for personalised welcomes (returning user vs new, channel-specific tone). |
| **Send message** | *Send message* | A fixed greeting with optional quick-reply chips. Best for simple welcomes. |
| **A welcome workflow** | *(workflow name, e.g. `runWelcomeWorkflow`)* | Pick any workflow registered for welcome use. Use this when the greeting needs to *do* something first (look up a customer, show rich media). The picker lists each workflow as its own option. |
The default for fresh bots is **Instruct super agent**. Quick-reply chips ("Conversation starters") are available in both Instruct and Send message modes - they appear under the message body on the same Profile settings page.
> **The two non-Instruct options skip the LLM.** Both **Send message** and **welcome workflows** are *deterministic* - they emit a pre-built or workflow-rendered message without a model round-trip on the welcome turn. Only **Instruct super agent** generates the welcome via the LLM. Pick a workflow option when you need to *do* something on welcome (look up the customer, render rich media) without the cost or latency of an LLM call.
If you choose a static response, you can add **quick reply chips** so users have suggested next actions.
**Best practices**
- Keep welcomes short. Long welcomes scare users away on chat.
- Show 2-4 quick-reply chips for the most common journeys. More than 4 becomes noise.
- If your welcome needs personalisation but no lookups, **Instruction** is usually the right choice. For lookups (loyalty status, account info), do them in a [workflow tool](../tools/index.md) called *after* the welcome.
---
**Next:** [Conversation Rules](conversation-rules.md) - the persona-level *always do* / *never do* guidelines applied to every reply.
---
## Routing Logic
**Routing Logic** is an optional Nexus surface where you write plain-English rules that override or refine how each message is routed between agents and tools.
> **Routing Logic rules are NOT mandatory.** Most Nexus bots route correctly with no rules at all - routing reads each agent's **Trigger** and picks based on that. Reach for Routing Logic only when you want a *deterministic* override on top of trigger-based routing.
## How routing actually works
Every turn, one of three things happens: the message is answered directly, it is handed off to one of your **agents** (conversational agents - the LLM-driven specialists; a [guided agent](../guided-agents/index.md) is reached as a **tool**, not a routing target), or a **tool** is called.
The primary signal is **each agent's Trigger** - the natural-language description you write at the top of an agent's profile that says *when* that agent should take over. Routing reads every agent's Trigger and picks the best match against the current user message.
*Example Trigger:* "When the user wants to book or schedule a test ride, request a quote, ask for a callback, share contact details, or says they are interested in buying a bike soon."
If your Triggers are sharp and non-overlapping, this is enough - you don't need anything else.
**Routing Logic rules** are the override layer. Add a rule when:
- Two agents have overlapping Triggers and routing keeps picking the wrong one.
- You want a topic to *always* go to a specific agent, with no LLM judgement involved (sensitive topics, regulated content, escalations).
- You need a compound condition that's hard to express in a Trigger ("if region = X **and** topic = Y, route to…").
When a rule applies, it overrides the trigger-based pick. When no rule applies, the router falls back to the Triggers.
The same model applies to **tools**: any tool can be called directly, using each tool's description (and the agents the tool is attached to) as routing signals. Write a Routing Logic rule when you need a topic to *always* go through a specific tool.
> **Scope what routing can read.** The routing decision reads memory and user properties as context. To restrict which variables the router — and the fallback reply — are allowed to see, set [**Allowed variables**](memory.md#allowed-variables-per-agent-read-scope) on the super agent. Leave it empty for no restriction (the default).
### Start trigger = the agent's Trigger {#routing-logic-vs-start-triggers}
The field labelled **Trigger** at the top of each agent's profile is sometimes called the agent's **Start trigger**. It's the same thing - the natural-language description that routing reads to decide *when* this agent should activate. Don't confuse it with **Routing Logic**:
| | Start trigger (per agent) | Routing Logic (Configuration) |
|---|---|---|
| **Where it lives** | At the top of each agent's profile, in the **Trigger** section | On the **Configuration → Routing logic** sub-page |
| **What it does** | The primary routing signal - read on every turn to pick the best matching agent | Optional override rules that pin specific topics to specific agents/tools |
| **Mandatory?** | Yes - every agent needs a Trigger | No - bots route fine with no rules |
You almost always start by writing sharp Triggers. Reach for Routing Logic only after you've seen routing-logic-vs-trigger collisions in real conversations.
## When to use Routing Logic vs Conversation Rules
People often mix these up. Here's the rule of thumb:
| You want to… | Use |
|---|---|
| Force a topic to always go to a specific agent or tool | **Routing Logic** |
| Set tone, style, "always do / never do" guidelines | **Conversation Rules** |
Routing Logic = hard constraints on **routing decisions**.
Conversation Rules = soft guidance on **how to talk**.
When the two collide, Routing Logic wins.
## Step 1: Open the Routing logic page
Go to **AI Agent → Configuration** and click **Routing logic** (under **Agents** in the left menu). The page only appears for Nexus agents.
The page header says *"Rules to help disambiguate and refine agent routing"* - that's accurate. Agent **Triggers** alone get you a long way; add rules only when you need to tighten. Rules are numbered and capped at **30 per bot**.
## Step 2: Add a rule
Click **Add rule**. Type your rule in plain English. Keep it concise - one or two short sentences usually beats a paragraph.
## Step 3: Write rules that are testable
A good rule meets all three of these:
1. **It names the trigger.** What user message or condition does this rule apply to?
2. **It names the action.** Which agent or tool should fire?
3. **It can be proven by a single test conversation.**
### Examples that work
- "If the user mentions billing, invoices, or refunds, hand off to the **@billing-agent**. Do not answer billing questions yourself."
- "If the user asks about an order's status, route to the **@order-status-agent** and call the `getOrderStatus` workflow before composing a reply."
- "If the user wants to book a demo, hand off to the **@demo-booking-agent**."
- "If the user types 'agent' or 'human', transfer to a live agent immediately. Do not try to resolve the issue first."
### Examples that don't work
- "Be helpful." → Not testable. Move to Conversation Rules - and even there, it's too vague.
- "Route correctly." → Doesn't name a trigger or an action.
- "If billing, route." → Names the trigger and action but ambiguously; "billing" could mean many things, and the rule doesn't say *where* to route.
## Step 4: Reference agents and tools by name
When your rule names an agent or tool, use **`@`-mentions** instead of typing the name as plain text. Type `@` in the rule editor to open the picker - pick the agent, workflow, or tool, and it inserts a live chip:
> "If the user mentions billing, invoices, or refunds, hand off to the **@billing-agent**. Do not answer billing questions yourself."
The chip is linked to the target's slug, so it resolves to the current name even if you later rename `billing-agent` to `billing-team`. Plain text doesn't - it goes stale silently.
A mention inside a rule is still just a *reference* - it's the rule that makes the handoff happen. Mentioning an agent in your bot identity, by contrast, doesn't route anywhere. See [`@`-mentions vs agent handoff](../agents/conversational-agents.md#mentions-vs-handoff).
## Step 5: Save and test
Click **Save**. Then open any agent and click the **play (▶)** icon in the title bar to launch the Playground.
For each rule you wrote:
1. Send a prompt that should trigger it.
2. Confirm the expected agent's persona takes over (or the expected tool fires).
3. If the wrong thing happens, your rule wording isn't specific enough - or an agent's **Trigger** is competing for the same topic. Tighten the rule (more precise trigger words, clearer action), or sharpen the Triggers of the agents involved, and retry.
## Best practices
- **Start with Triggers, add rules when needed.** A precise agent **Trigger** handles most routing on its own. Add a routing rule when (a) Triggers overlap and routing isn't picking the agent you want, (b) a topic is sensitive enough that you don't want it answered directly, or (c) you need a compound condition Triggers can't express.
- **One rule, one concern.** "If the user mentions billing or asks about an order, route to billing or fulfillment" is a compound rule. Split it into two separate rules.
- **Order doesn't matter much.** Rules are evaluated together as a constraint set, not top-to-bottom. Don't agonize over ordering.
- **Test edge cases.** Users phrase things weirdly. After the obvious test prompt works, try misspellings, partial matches, and adjacent topics that should *not* match.
- **Prefer specific over clever.** "If the user mentions cancellation" is better than "If the user wants to leave."
- **Keep a list of test prompts** alongside your rules. When you tweak wording later, you'll have a regression check ready.
## Common pitfalls
- **Vague triggers.** "If the user is upset" - what counts as upset? Use concrete signals: "If the user mentions 'frustrated', 'angry', 'unacceptable', or types in all caps, …".
- **Contradictory rules.** Two rules pointing at different agents for overlapping triggers will produce inconsistent routing. Re-read your list whenever you add a rule.
- **Fighting your own Triggers.** If your rule and the agent's Trigger point in different directions ("route refunds to support-agent" but the billing-agent's Trigger claims it handles refunds), routing will feel unpredictable. Keep rules and Triggers consistent.
- **Forgetting to add a "do not" clause.** "Route billing to billing-agent" is good. "Route billing to billing-agent. Do not answer billing yourself." is better - the second sentence stops the message from being answered directly instead of routed.
Continue to: **[Conversational agents](../agents/conversational-agents.md)**.
---
## Voice settings
> **Note:** Voice settings is part of **Configuration**, so it is **project-level** - it applies to every agent in the bot, conversational and guided alike.
Voice settings is where you configure how your bot sounds and listens. It's the **Voice settings** sub-page inside **AI Agent → Configuration**, alongside Profile settings, Conversation rules, and Routing logic.
## Step 1: Open Voice settings
In your bot, go to **AI Agent → Configuration** and click **Voice settings** in the left menu.
The page is split into four sections:
1. Voice Configuration (mode, provider, voice).
2. Voice Instructions.
3. Audio Settings.
4. Advanced VAD.
You can leave most defaults alone for a first build - the only sections you must touch are the first two.
## Step 2: Pick a mode
The first decision is **Mode**. Two options:
| Mode | What you get |
|---|---|
| **Text & TTS** *(default)* | Speech recognized → text answered by your agent → text spoken back. Three independent stages, lots of provider choice. |
| **Realtime Audio** | Realtime audio API (OpenAI today; multi-provider adapters in flight for Gemini Live, Anthropic, MiniMax). Audio straight in, audio straight out - lowest end-to-end latency. Now supports registered tools (DynamicTool / MCP / KB), mid-call agent switch, greet-on-connect, per-turn traces. |
**How to choose:**
- Stick with **Text & TTS** when you need the widest provider catalog, broadest language coverage, and access to your custom voices.
- Pick **Realtime Audio** when end-to-end latency matters more than fine-grained provider control. With the May 2026 update, realtime has reached parity with pipeline mode on tools, agent switching, and traces - it's a viable production option for new builds, not just demos.
You can switch between modes any time. Each mode has its own voice and provider list, so you'll re-pick a voice if you change.
> **Realtime mode internals:** routing is driven by the existing UI-editable `voiceOptions.mode === "realtime"` field - no separate feature flag. Schema config (`provider`, `audio.{input,output}SampleRate`, `audioFormat`, `greetOnConnect`) is exposed through the same Voice Settings sub-page; defaults are sensible for the OpenAI provider.
## Step 3: Pick a provider (Text & TTS mode)
The **TTS Provider** dropdown lists what's available for the speak-back stage. Currently:
| Provider | Notes |
|---|---|
| **Yellow AI** | The default. Good general quality, broad language coverage, and full access to your custom voices. |
| **ElevenLabs** | Premium voice quality, strong English. 10 built-in presets (Rachel, Domi, Bella, Antoni, Adam, etc.). |
| **MiniMax** | Multilingual presets including Mandarin, Japanese, French, Spanish. |
Speech-to-text (STT) provider is configured separately in pipeline runtime config. Yellow AI is the default STT choice.
## Step 4: Pick a voice
The **Voice** dropdown shows every voice available for the chosen provider:
- Built-in presets (Rachel, Domi, Bella, etc. for ElevenLabs; Mandarin and multilingual options for MiniMax).
- Yellow's **global curated voices**.
- **Your custom voices** - anything you've cloned for this bot. See [Custom Voices](../../voice/custom-voices.md).
Click the play icon next to a voice to preview it before saving.
**Best practice:** match the voice to your audience. A persuasive sales bot wants a different voice than a calm support bot. Preview a few before committing.
## Step 5: (Realtime Audio mode) Pick an OpenAI voice
If you switched to Realtime Audio, the voice list narrows to OpenAI's options: Alloy, Ash, Ballad, Coral, Echo, Sage, Shimmer, Verse, Marin, Cedar.
Each has a distinct character - preview to pick.
## Step 6: Write voice instructions
The **Voice Instructions** field (≤500 characters) is freeform text that biases the bot's spoken behavior:
- "Respond only in Hindi, even if the user types in English."
- "Speak slowly and clearly. Pause briefly between sentences."
- "Sound friendly but concise - keep replies under two sentences."
**Best practices:**
- Use this for **delivery** (pace, tone, language); use **bot identity** for *what* to say.
- Don't repeat your bot identity here. Voice instructions layer on top.
- For multilingual bots, this is often the cleanest place to lock the spoken language.
## Step 7: Audio Settings
There's currently one option here:
- **Noise Cancellation** - on by default. Suppresses background noise on the user's mic. Leave it on unless you have a specific reason (some studio setups can do better with raw audio).
## Step 8: Advanced VAD (Voice Activity Detection)
VAD is what tells the bot "the user has finished speaking, my turn." Default values work for most calls; tune only if testing reveals a specific problem.
| Setting | Default | What it does |
|---|---|---|
| **VAD Threshold** | 0.85 | How aggressively to detect speech vs silence. Higher = stricter (less likely to trigger on background noise but may cut off quiet speech). |
| **Prefix Padding** | 300 ms | How much audio *before* detected speech to include. Keeps the start of words from being clipped. |
| **Silence Duration** | 500 ms | How long the user must be silent before the bot considers the turn ended. Lower = snappier, more interruptions; higher = more natural pauses, but a small delay. |
**Tuning by use case:**
- **Outbound sales / fast-paced chat** → drop Silence Duration to ~300 ms; you'll feel more responsive.
- **Slow / elderly / non-native speakers** → raise Silence Duration to 700-800 ms so the bot doesn't cut them off.
- **Noisy environments** (vehicles, public spaces) → raise VAD Threshold to 0.9.
## Step 9: Save
Click **Save**. The configuration applies to all conversations on this bot from the next call onward.
## Best practices
- **Pick the mode that matches your goal**, not the newest one. Pipeline (Text & TTS) is right for most production bots.
- **Preview voices before committing.** A 10-second preview saves a lot of "this voice is wrong" feedback later.
- **Keep voice instructions short and behavioral.** This isn't where you re-state the agent's purpose.
- **Don't change VAD without a measurement.** Test the bot, find a specific problem, then tune. Random changes can make things worse.
- **For multilingual bots, set the spoken language explicitly** in Voice Instructions. Don't rely on auto-detection unless you've tested it on real calls.
Continue to: **[Custom Voices](../../voice/custom-voices.md)**.
---
## The Conversational Agent node
A **Conversational Agent node** is the workhorse of a [guided agent](index.md). It embeds a single focused conversational turn - one job, with explicit exits - inside the flow you design on the [flow canvas](flow-canvas.md). The node speaks to the user, follows its instructions, and finishes by choosing one of the **exits** you defined; each exit is wired to whatever comes next.
Think of it as a small, sharply-scoped agent that the flow *invokes* at exactly the right moment. It does not have a trigger and it is never picked by routing - the flow decides when control reaches it. That's the whole point of a guided agent: the order is fixed, so every run is consistent and auditable.
Ask the [AI layer](../../ai-layer/index.md) to scaffold a Conversational Agent node - it can draft the instructions, suggest exit labels and descriptions, and wire the exits into your flow, then wait for your confirmation before saving.
## How it differs from a standalone conversational agent
A [conversational agent](../agents/conversational-agents.md) and a Conversational Agent node share the same engine - an LLM that reads the conversation, uses tools, and replies - but they sit in very different places:
| | Conversational agent | Conversational Agent node |
|---|---|---|
| **Lives** | On the Agents page (Conversational tab) | Inside a guided agent, on the flow canvas |
| **How it's reached** | Routing **routes** to it based on its **Trigger** | The **flow** hands control to it - no trigger, no routing |
| **Scope** | Owns a whole domain ("billing", "order status") and reasons openly | Owns **one step** and finishes on an explicit exit |
| **Finishes by** | Returning control for routing when it's done | Choosing one of its **exits**, which decides the next node |
| **Lifecycle** | Has Live / Draft status, an avatar, conversation rules | No status - it's part of the flow's lifecycle |
> **Note:** Because they share an engine, the writing skills carry over. A good Trigger on a standalone agent and a good exit description on a node are the same craft: say precisely what's true when the agent is done. The difference is that a node's outcome is a *branch in a flow*, not a handoff back to a router.
## Open the node
Click the node on the canvas to open its **configuration drawer**. The drawer header shows the node's **Name** and a **Version history** button (to review and restore earlier versions of the node), with **Cancel** and **Save** at the bottom. Nothing you change is committed until you click **Save**.
The drawer has two columns:
- **Left** - Name, Capabilities (Tools, Rich Media, Variables), First response, and Exits.
- **Right** - Instructions (the rich-text goal/prompt).
## Name
Give the node a name that says what the step *does* - `identify-request`, `collect-shipping-address`, `confirm-order`. The name appears on the node in the canvas and in run logs, so a self-explanatory name makes the flow readable at a glance and easier to debug later.
Keep it a verb-phrase for the task, not the domain. `collect-address` reads better on a node than `address-agent`.
## Instructions
The **Instructions** editor (the right column) is the node's **goal and prompt** - what this single agent should accomplish and how it should behave while it's in control. It's a rich-text editor with the usual formatting (bold, italic, underline, strikethrough, headings H1-H3, lists, code, quote, divider, table) and markdown shortcuts, so you can structure longer instructions clearly.
You can **`@`-mention tools** inside the instructions - for example `@Quick Replies` - to reference a capability you've attached to the node. The mention stays linked to the tool even if it's renamed.
Write instructions for a node, not for an open-ended assistant. A node has one job:
- **State the single goal** in the first line. "Your job is to find out whether the customer wants a return or an exchange."
- **Tell it to finish on an exit, not with a message.** A node ends by choosing an exit. Instruct it to stop talking once the outcome is clear: *"As soon as you know which one it is, finish on the matching exit. Do not send any extra message."* Without this, agents tend to append a chatty "Great, I'll help you with that!" before exiting, which the next node may then repeat.
- **Scope it hard.** A node should not wander outside its step. The most reliable pattern is to say so explicitly: *"This agent can do nothing beyond what is described here. If the user asks about anything else, finish on the `out_of_scope` exit."* That single line stops a step from quietly turning into a general-purpose chatbot mid-flow.
- **Be specific about what to collect or decide**, and in what shape, especially if a later node or tool depends on it.
A generic example for a node that decides between a return and an exchange:
```
You are the first step in an order-return flow. Your only job is to find out
whether the customer wants a RETURN (send the item back for a refund) or an
EXCHANGE (swap it for a different size or variant).
Ask one short question to clarify if it isn't already obvious from what the
user said. If the customer asks for anything outside returns and exchanges
(order status, cancellation, a human), do not try to handle it.
As soon as the intent is clear, finish on the matching exit and send no
further message. You can do nothing beyond this - you only classify the
request into return or exchange.
```
> **Tip - keep instructions narrow on purpose.** The reason guided agents are predictable is that each node is small. If you find a node's instructions growing to cover three jobs, that's a sign it should be three nodes wired together - not one node with a long prompt.
## Capabilities
The **Capabilities** group (left column) gives the node the means to do its job. Each row has an **Add** control to attach more.
| Capability | What it does |
|---|---|
| **Tools** (`+ Add tool`) | The actions this node can take - run a [workflow](../tools/workflows.md), search a [knowledge base](../tools/knowledge-base.md), escalate to a human, and so on. Tools are defined once in **AI Agent → Tools** and any agent or node in the bot can use them. Attach only the tools this step actually needs. |
| **Rich Media** (`+ Add`) | UI elements the node can present - for example a **Quick Replies** chip set for the user to tap instead of typing. Once attached, reference it from the instructions with an `@`-mention (e.g. `@Quick Replies`) so the agent knows to show it. |
| **Variables** (`+ Add`) | The flow's **local memory** - named values this node can read and write so that later nodes can use them. See [Memory & conversation history](#memory--conversation-history) below. |
Keep a node's capabilities tight. A node with one tool and one variable is far easier to predict and debug than one carrying every tool in the bot. If two nodes need the same tool, attach it to both - that's fine and expected, since tools are shared across the bot.
## First response
**First response** is a toggle in the left column, **OFF by default**, labelled *"The agent's first response when control reaches it."* It's the optional opening message the node speaks the moment the flow hands it control.
- **Turn it ON** when the node should **greet or announce** on entry - "Let's get your return started" before it begins asking questions, or a short status line when the flow moves into a new phase. The message you set here is sent before the agent does anything else.
- **Leave it OFF** (the default) when the node should **act silently** - just follow its instructions without a canned opener. This is usually right for steps in the middle of a flow, where a fresh greeting would feel repetitive. With the toggle off, the node simply does its job per its instructions the moment it takes over.
> **Tip:** Use First response sparingly. One announcement at the *start* of a flow reads naturally; an announcement on every node makes the conversation feel like it keeps restarting. For most mid-flow nodes, leave it off and let the instructions carry the turn.
## Exits
**Exits** are how a node *finishes*. Each exit is one outcome the agent can land on, and the list lives at the bottom of the left column.
Every exit has:
- a **label** - a short chip (e.g. `return`, `exchange`, `max_retry`), used to wire the branch on the canvas and shown in logs;
- a **description** - natural language that tells the agent *when this outcome is true* (e.g. an intent exit → "if the intent is a return"; a `max_retry` exit → "when the user can't decide after 3 attempts"); and
- a **delete (×)** to remove it.
Add more with **`+ Add exit`**.
### How the agent chooses an exit
When the agent decides its job is done, it reads the exit **descriptions** and picks the one that best matches the current state of the conversation, then finishes on it. The label is just the wiring handle - **the description is what the model matches on.** Vague descriptions lead to the wrong branch; sharp, mutually-exclusive descriptions lead to reliable branching.
### Conventions
Two exits show up on almost every node:
- **`max_retry`** - a safety valve for when the agent can't get a clean outcome after a few attempts (e.g. "when the user can't decide after 3 attempts" or "after 3 failed validation attempts"). Wire it to a recovery node - re-ask, offer a human, or hand off - so the flow never gets stuck looping.
- **`on_error`** - a node also exposes an **`on_error`** handle on the canvas for failures (a tool errored, something broke mid-step). Wire it to a graceful fallback rather than leaving it dangling, so an unexpected failure lands somewhere sensible instead of stalling the run.
### Writing exit descriptions the agent can match
- **Make them mutually exclusive.** "if the intent is a return" and "if the intent is an exchange" don't overlap. "if the customer seems unhappy" and "if there's a problem" do - the agent will hesitate between them.
- **Describe the *condition*, not the next step.** Write "if the user wants to swap for a different size", not "go to the exchange handler". The agent matches on the situation; the canvas owns where it goes.
- **Cover the unhappy paths.** Add an exit for "the request is outside returns and exchanges" or for "the user wants a human" so those don't get forced into one of the main branches.
- **Keep the set small.** Two to five exits per node is the sweet spot. If you need ten, the node is doing too much - split it.
## How exits drive the flow
An exit isn't just an outcome - it's a **branch**. On the [flow canvas](flow-canvas.md), each exit you define becomes an **output handle** on the node, and you connect that handle to the next node. The agent finishing on exit `return` is exactly what makes the flow follow the `return` branch.
So the loop is:
1. You define exits on the node (label + description).
2. Each exit appears as a branch handle on the node in the canvas.
3. You wire each branch to a target node (the `on_error` handle too).
4. At runtime, the agent picks an exit; the flow follows that branch to the wired node.
Because of this, **every exit should go somewhere.** An unwired exit is a dead end - if the agent picks it, the run has nowhere to go. The canvas highlights unwired branches; see [Build on the flow canvas](flow-canvas.md) for how to connect them and for the other node types you can wire to (a [workflow](../tools/workflows.md) via an Execute Workflow node, a human via Transfer to Agent, another Conversational Agent node, and so on).
## Memory & conversation history
A node has two ways to carry context.
**Variables (flow-local memory).** The **Variables** you attach under Capabilities are the flow's local memory: named values a node can write and later nodes can read. Use them to pass a decision or a collected value down the flow - `return_or_exchange`, `order_id`, `preferred_size`. A variable a node writes is available to every node after it in the same run.
This is the same memory model used across Nexus - a node's local variables and the bot's [global memory](../configuration/memory.md) share one per-customer pool at runtime, so a node can also read values written elsewhere in the conversation. See [Memory in Nexus agents](../configuration/memory.md) for the full picture: when to use a variable vs a tool input, naming conventions, and how runtime sharing works.
> **Tip:** Pass a *decision* down the flow as a variable rather than re-deriving it in a later node. If the first node already decided `return` vs `exchange`, store it; don't make a downstream node ask again.
**Conversation history.** A node can also be given the **prior conversation history** so it has the context of what's already been said. Turn this on for a node when its job depends on earlier turns - for example a node that confirms details the user gave several steps ago, or that needs to interpret a follow-up like "the second one". Leave it off for a clean, self-contained step that only needs the user's current input; that keeps the node focused and the prompt smaller.
## Conversation rules
Your primary agent can define **[global conversation rules](../configuration/conversation-rules.md)** - shared behaviour guidelines (tone, do's and don'ts) that every agent, including each node in a flow, follows automatically.
An agent node inherits those rules by default. Turn **Apply global conversation rules** off for a node that should ignore them - for example a tightly scripted step whose exact wording those general rules would interfere with. The choice is per node: the same agent placed in another node still follows the rules there unless you turn it off on that node too.
> Routing rules (which decide *which* agent handles a turn) are never sent to a flow agent node - the flow, not the model, controls the order - so this setting only concerns the behaviour rules above.
## Lifecycle Hooks
The **Lifecycle Hooks** section (left column) lets a node run a **workflow** at a set moment in its lifecycle, separately from its exits. The available event today is **When the turn ends** - the hook fires after the node finishes a turn, before control moves on. The node **waits for each hook to finish** before continuing.
Each hook has an **event** (when the turn ends), a **workflow** to run, and optional **conditions** that decide whether the workflow actually runs.
### Conditions
A hook runs on every matching event unless you add conditions to narrow it. The condition chip reads **"Always"** when there are none, or **"N condition(s)"** once you add some.
Open the editor to build a condition set:
- **Variable** - click *Select a variable* and pick the value to test. Variables can come from **memory**, **journey** (values owned by the current flow run, seeded when the node is entered), **profile**, **user**, or **system** scope.
- **Operator** - one of **is** (equals), **is not**, **is empty**, or **is filled in**.
- **Value** - for **is** / **is not**, supply the value to compare against. A boolean variable shows a yes/no selector; other types show a value box.
- **Quantifier** - when you add more than one condition, choose whether **all of these are true** (AND) or **any of these are true** (OR).
Comparisons are **type-aware**: a boolean or number condition matches only its exact value (`true` matches the boolean `true`; `42` matches the number `42`), and strings compare exactly. So a condition on a boolean variable won't accidentally match the string `"true"` written elsewhere.
> **Tip:** Use a turn-end hook with a condition for fire-and-forget side effects that should only happen in certain states - log a transcript only when `escalated` is true, or push a CRM update only once `order_id` **is filled in**. Keep the reply logic in the node's instructions and exits; use hooks for the "and also, when X, do Y" work.
## Example: a generic router node
A common first node in a flow is a small **router** that classifies the request and branches. Here's a fully generic one for an order-management flow.
**Name:** `identify-request`
**First response:** OFF (this node should just ask its question, not greet again).
**Instructions:**
```
You are the first step in an order-management flow. Your only job is to
identify whether the customer wants a RETURN (send an item back for a refund)
or an EXCHANGE (swap it for a different size or variant).
If it's already clear from what the user said, don't ask - just classify.
Otherwise ask one short question to clarify. Offer @Quick Replies so the user
can tap "Return" or "Exchange".
As soon as the intent is clear, finish on the matching exit and send no extra
message. If the customer can't decide or keeps going back and forth, finish on
max_retry after three attempts. You can do nothing beyond classifying the
request into a return or an exchange.
```
**Capabilities:** Rich Media → **Quick Replies** (`Return`, `Exchange`).
**Variables:** `return_or_exchange` (written by this node so later steps can read it).
**Exits:**
| Label | Description |
|---|---|
| `return` | if the customer wants to send an item back for a refund |
| `exchange` | if the customer wants to swap an item for a different size or variant |
| `max_retry` | when the customer can't decide after 3 attempts |
On the canvas you'd then wire `return` to your return flow, `exchange` to your exchange flow, and `max_retry` to a recovery node (offer a human, or re-ask once more). The `on_error` handle goes to the same graceful fallback. Now every run routes the same way, and the logs show exactly which exit fired and why.
## Best practices
- **One node = one job.** If you can't name the node's single task in a short verb-phrase, it's doing too much. Split it into wired nodes.
- **Sharpen exit descriptions.** The description is what the agent matches on. Make them specific and mutually exclusive; that's where branching reliability comes from.
- **Tell the node to exit silently when matched.** Add "finish on the matching exit and send no extra message" to the instructions so steps don't append chatter that the next node repeats.
- **Always handle the unhappy paths.** Add a `max_retry` exit and wire `on_error`. Every exit and handle should go somewhere - no dead ends.
- **Keep instructions scoped.** Use the "this agent can do nothing beyond these instructions" pattern so a step can't drift into a general chatbot.
- **Keep capabilities lean.** Attach only the tools and variables the step needs. One tool, one or two variables per node is a healthy default.
- **Reuse via tools, not by widening a node.** When several nodes need the same action, attach the same shared tool to each - don't pile capabilities onto one node to serve many steps.
- **Pass decisions forward as variables.** Store what a node decides so downstream nodes don't re-ask.
Continue to: **[Test a guided agent](testing.md)**.
---
## Guided agents best practices
A guided agent is only as good as the way you've broken the work down. The builder makes it easy to wire nodes together - these practices keep the result predictable, debuggable, and safe to publish. Read them after you've built your first flow on the [flow canvas](flow-canvas.md) and configured a [Conversational Agent node](agent-node.md).
Ask the [AI layer](../../ai-layer/index.md) to scaffold a guided agent from a one-line description of the steps. It drops the nodes, drafts each node's instructions and exits, and waits for your confirmation before saving - a fast way to get a first draft you then tighten with the practices below.
## Choose guided when the steps must be consistent
The first decision is whether the use case even wants a guided agent. Use this table.
| Build a… | When the work is… | Examples |
|---|---|---|
| **Conversational agent** | Open-ended - the answer is worked out per message from your knowledge, and the path varies user to user. | Troubleshooting, support, diagnosing errors, guiding someone to a resolution step by step. |
| **Guided agent** | Multi-step and **must run the same way every time** - every run should be consistent and auditable, with nothing skipped. | Order returns, loan applications, KYC checks, booking an appointment. |
If you can't predict the order of steps, you want a conversational agent. If skipping a step is a compliance or correctness problem - collecting consent, verifying identity, confirming an amount before a charge - you want a guided agent so the sequence is enforced, not left to the model's judgement.
> **Tip - start conversational, graduate to guided.** If a conversational agent keeps getting one multi-step journey wrong (it asks for things out of order, or finishes without confirming), that's the signal to rebuild *that journey* as a guided agent. You don't have to convert the whole bot.
## One node, one job
Each Conversational Agent node should do exactly one thing and then exit. "Collect the order ID", "Check return eligibility", "Book the pickup slot" - three nodes, not one node trying to do all three.
Why this matters:
- **Adherence.** A node with a single, scoped goal follows its instructions far more reliably than one juggling several.
- **Debuggability.** When a run goes wrong, a narrow node tells you exactly which step failed. A do-everything node leaves you guessing.
- **Reuse of exits.** Distinct jobs produce distinct outcomes, which gives you clean exit labels to branch on (see below).
A good test: if you can't name a node in three or four words ("Collect order ID"), it's probably doing too much. Split it.
> **Note:** "One job" is about the node's *goal*, not its turn count. A single node may take several turns with the user to finish its one job (ask, re-ask on bad input, confirm) - that's fine. What you're avoiding is one node owning multiple *unrelated* jobs.
## Write sharp exit labels and descriptions
A node's **Exits** are the outcomes it can finish on. Each exit is a short label chip plus a natural-language description, and each exit is what you wire a branch from. Good exits are the backbone of a reliable flow.
- **Label = the outcome, in a word or two.** `eligible`, `not_eligible`, `slot_booked`, `max_retry`. The label is what shows on the node's output handle and what you connect on the canvas, so keep it short and meaningful at a glance.
- **Description = when this exit fires, in plain language.** This is how the agent decides which exit to take, so be specific: "if the item is within the 30-day window and unopened" beats "eligible". For a retry exit, describe the give-up condition: "when the user can't provide a valid order ID after 3 attempts".
- **Cover the unhappy paths.** Don't only model success. Add exits for the user refusing, an item being out of policy, or the agent running out of retries - otherwise the flow has nowhere to go when reality doesn't cooperate. The runtime also surfaces an **`on_error`** path for unexpected failures; wire it somewhere graceful (a handoff, an apology, a retry), don't leave it dangling.
> **Tip - match exits to branches.** Every exit you define should map to a distinct downstream behaviour. If two exits always go to the same next node, they probably should be one exit. If one exit needs to fork based on a value, that decision belongs in the *next* node's instructions and its exits, not crammed into this one.
## Wire every exit
An exit with nothing connected to it is a dead end: when the agent finishes on that outcome, the run has nowhere to go. Before you publish, walk every node and confirm each exit handle - including `max_retry` and `on_error` - connects to a next node (or to a deliberate end of the flow).
Practical habit: build the happy path end-to-end first, then go back and wire each node's failure and retry exits. Common destinations for the unhappy paths:
- An **Execute Workflow** node that logs the drop-off or files a ticket.
- A **Transfer to Agent** node that hands the user to a human when the flow can't resolve it.
- Back to an earlier node to re-collect input (a back-edge to a *different* node - for example, "amount wrong" routing from a confirm node back to the collect node).
Use the canvas auto-layout and minimap to scan for orphaned handles, and run the flow in **Execute** to catch any branch that silently terminates.
## Keep each node's instructions scoped
A node's **Instructions** are its goal and prompt - the rich-text editor in the right column of the node config. Write them for the one job the node owns, and nothing else.
- **State the goal, the inputs to collect, and the finish condition.** "Collect the order ID. Validate it's an 8-digit number. When you have a valid ID, finish on `collected`." Leave routing decisions to the exits.
- **Don't restate the whole journey in every node.** The flow's structure carries the sequence; each node only needs to know its own step. Repeating the end-to-end process in node after node makes them drift and contradict each other.
- **Reference capabilities by `@`-mention.** If the node uses a tool or rich-media item (for example a "Quick Replies" chip), `@`-mention it inside the instructions so the reference stays linked even if the target is renamed.
- **Use the node's capabilities for what they're for.** Put data the step needs to remember into **Variables** (the flow's local memory), put actions into **Tools**, and keep the **First response** toggle off unless the node genuinely needs a canned opener - by default the node acts per its instructions without a scripted opening line.
> **Note:** Scoped instructions and the "one node, one job" rule reinforce each other. If a node's instructions are getting long and start branching ("if X do this, else do that"), that's usually a sign the node should be two nodes with an exit between them.
## Use guided agents as tools from conversational agents
Guided agents are automatically **available as tools** to your conversational agents - there's no toggle to enable. This is the recommended way to combine the two styles: let a conversational agent handle the open-ended conversation, and call a guided agent when the user reaches a step that must run deterministically.
A typical pattern:
- A conversational **support agent** diagnoses a problem in free-form conversation.
- When the resolution is "process a return", it invokes the **order-return guided agent**, which runs the fixed collect → check → book sequence.
- When the guided agent finishes, control returns to the conversational agent to wrap up.
This keeps each style doing what it's best at: conversation where the path varies, guided where the steps can't. See [Conversational agents](../agents/conversational-agents.md) and the [Configuration](../configuration/index.md) guide for how the conversational side routes work, and [routing logic](../configuration/routing-logic.md) for making the handoff deterministic when you need it.
## Test before you publish
A guided agent has no Live/Draft status - when you **Publish**, it's live. So validate it first, the same way you would any agent.
- **Run it on the canvas.** Use the **Execute** tab to walk the flow turn by turn, and the **Logs** tab to see which node fired, which exit it took, and what each variable held. This is the fastest way to catch a mis-wired branch or an exit description that's firing on the wrong condition.
- **Test the unhappy paths, not just the happy one.** Feed it bad input, refusals, and out-of-policy cases. Confirm `max_retry` and `on_error` lead somewhere graceful. Most guided-agent bugs live in the branches you didn't think to exercise.
- **Add test cases in the Trust Centre.** For repeatable, multi-turn coverage - and to keep the flow honest as you change it - build test cases in the [Testing Lab](../../test-debug/index.md). Run them before every publish.
> **Tip - debug from the Logs tab.** When a run does something unexpected, the Logs tab tells you the *exact* node and exit, so you can fix the right node's instructions or exit description instead of guessing. Treat a surprising exit choice as a prompt to sharpen that exit's description.
## A few things to keep in mind
These are builder-level realities to design around, not bugs:
- **Each node mints its own agent.** A Conversational Agent node's configuration is local to that node - you don't share one agent across multiple nodes. If two steps need the same behaviour, configure both nodes (or factor the shared logic into a workflow you call from each via an **Execute Workflow** node).
- **Branch on outcomes, not on raw values inside one node.** Decisions belong in exits. If you find a node trying to decide between many downstream paths, give it more exits or split it.
- **Name the flow uniquely.** Two guided agents can't share a name.
## Read next
- **[Guided agents overview](index.md)** - what a guided agent is and when to reach for one.
- **[Harness overview](../index.md)** - where guided agents fit alongside conversational agents and tools.
- **[Test and debug](../../test-debug/index.md)** - build test cases and run them before every publish.
---
## The guided flow canvas
A **guided agent** runs the exact steps you design, in the same order every time. You author those steps on the **flow canvas** - a visual node graph where each node does one job and the lines between them decide what happens next. Open a guided agent from the **Guided** tab on the [Agents page](./index.md), or create a new one from the [Create picker](../agents/create.md), and the canvas opens at `/build/flows/?from=guided-agents`.
This page is a tour of the canvas: the tabs and toolbar, the **Start** node, the node types you wire together, how **branches** connect them, and the **journey variables** that carry data across the flow. The [Conversational Agent node](./agent-node.md) - the workhorse node where most of your logic lives - is documented in depth on its own page.
Ask the [AI layer](../../index.md) to scaffold a guided agent from a one-line description. It lays out the Start node, the Conversational Agent nodes, and the branches between them on the canvas for you to refine - you don't have to drag every node by hand.
## The canvas tour
When you open a guided agent, the header carries the flow's name plus a few actions, and the body is a scrollable, zoomable node graph.
A guided flow is a graph of nodes wired by each node's **exits**. A typical order-return flow looks like this:
```mermaid
flowchart TD
S(["Start (trigger)"]) --> A["Conversational Agent nodeidentify the request"]
A -->|return| RET["Execute Workflowprocess the return"]
A -->|exchange| EX["Conversational Agent nodecollect the new variant"]
A -->|max_retry| HO["Transfer to Agent(human)"]
A -. on_error .-> HO
RET --> DONE(["End"])
EX --> DONE
```
### Tabs
The canvas has three tabs:
| Tab | What it's for |
|---|---|
| **Editor** | Build the flow - add nodes, write their instructions, and wire branches. This is where you spend most of your time. |
| **Execute** | Run the flow end to end and watch it step through your nodes, so you can confirm the path a given input takes. |
| **Logs** | Inspect past runs - which nodes fired, which exit each one took, and the variables along the way. Use this to debug a run that didn't go where you expected. |
### Toolbar actions
- **Run** - start a test conversation against the current draft of the flow, without publishing. Use it constantly as you build.
- **Publish** - make your edits live. Unlike conversational agents, a guided agent has **no Live/Draft status badge** in the list - publishing is how your canvas changes reach customers.
- **What's new** - release notes for the canvas itself.
- **Search for nodes** - a search box that finds a node by name and jumps to it. On a large flow with a dozen nodes, this is faster than panning the canvas.
### Navigating the graph
The canvas is a node graph built on React Flow. To find your way around:
- **Minimap** - a small overview of the whole graph in the corner; click or drag within it to jump to a region.
- **Zoom and fit** - zoom in/out and a fit-to-screen control to frame the entire flow.
- **Auto-layout** - re-tidies the nodes into a clean top-to-bottom arrangement after you've added or rewired several. Reach for it when the graph starts to look tangled.
> **Tip - let auto-layout do the tidying.** Don't fuss over pixel-perfect node placement while you build. Wire the logic first, then run auto-layout to make the flow readable. Position is cosmetic; the branches are what matter.
## The Start node
Every guided flow begins at a single **Start** node. It is the entry point of the graph and it carries the **trigger** - the natural-language description of *when* this guided agent should run.
The trigger plays the same role here that an agent's Trigger plays for a [conversational agent](../agents/conversational-agents.md#step-2-configure-the-agents-behaviour): it's how the bot decides this guided agent is the right thing to run for an incoming request. Write it the same way - concrete about the situations it covers, and explicit about what it does *not* handle.
> **Example trigger.** *"When the customer wants to return or exchange an item they've already received - start a return. Do not handle order tracking or delivery-status questions; those have their own agent."*
The Start node has exactly one outgoing edge: it hands control to the first real node in your flow (usually a Conversational Agent node). From there, the path is decided by each node's exits.
> **Note:** Guided agents are automatically **available as tools** to your conversational agents. A conversational agent can hand a multi-step task to a guided agent the same way it would call any other tool - you don't need to flip a separate "use as tool" toggle. See the [Agents page overview](./index.md) for how the two agent types relate.
## Node types you wire together
A guided flow is built from nodes, each with a focused job. You drop a node onto the canvas, configure it, and connect it to the next node by its exits. The most common node types:
| Node | What it does |
|---|---|
| **Start** | The flow's single entry point. Carries the trigger that decides when the guided agent runs. One per flow. |
| **Conversational Agent** | A focused agent that owns one step of the conversation - collect details, confirm a choice, answer a scoped question. It has its own instructions, tools, variables, and **exits** (the outcomes it can finish on). This is where most of your logic lives. See [The Conversational Agent node](./agent-node.md). |
| **Execute Workflow** | Calls a [workflow](../tools/workflows.md) - a callable, deterministic skill (an API call, a lookup, a record update). Use it when a step is pure business logic with no conversation, e.g. *check return eligibility* or *book a pickup slot*. Available in **every v3 flow**. |
| **Transfer to Agent** | Hands the conversation off to a human agent (or routes it onward). Use it as the exit path when the flow can't or shouldn't continue automatically - for example, an item outside the return window, or an explicit "talk to a person" request. |
The node search/palette offers **more node types** than the four above - open it from the canvas to see everything available for your bot. Build the backbone of your flow with Conversational Agent nodes, and reach for Execute Workflow and Transfer to Agent at the points where the journey leaves the conversation (to run logic) or leaves the bot (to reach a human).
:::caution
**A guided agent is never a "workflow."** "Workflow" is a reserved, distinct term - a callable scheduler skill you build in the workflow editor and invoke from an **Execute Workflow** node (or as a [Workflow tool](../tools/workflows.md)). The guided agent is the *conversation*; a workflow is a subroutine it can call. Don't conflate the two.
:::
## Branches and edges
Nodes connect to each other through **exits**. Each node finishes on one of its named exits, and each exit is an **output handle** that you wire - with a **branch** (the line on the canvas, an edge) - to the next node that should run.
How it works:
- A **Conversational Agent node** declares a list of **exits**, each a label plus a short natural-language description of when it applies. For example, an order-return node might exit on `eligible`, `not_eligible`, or `max_retry` (the user couldn't decide after a few attempts). Every node also has an **`on_error`** exit for the failure path.
- You connect each exit to a target node by dragging a branch from the exit's handle to the next node's input. That branch *is* the routing: when the node finishes on an exit, control follows that exit's branch.
- An exit that isn't wired anywhere **ends the flow** after that node. Wire the exits you want to continue; leave terminal outcomes (e.g. a successful completion) unwired to finish.
- Branches can point **forward** (collect → confirm) or **back to an earlier node** (e.g. *confirm → collect* to re-collect a changed detail), letting you build loops and retries.
Because every path is an explicit branch you drew, a guided agent's behaviour is **deterministic and auditable**: there's no path through the flow that you didn't wire. That predictability is the whole point of choosing a guided agent over a conversational one for multi-step, must-not-miss-a-step journeys.
> **Note:** An exit's *description* is for the **Conversational Agent node** - it's how that node's agent decides which outcome it has reached (e.g. *"if the intent is a return"*, *"when the user can't decide after 3 attempts"*). The *branch* is how the canvas turns that outcome into the next node. You author exits and their descriptions inside the node; you draw branches on the canvas. See [The Conversational Agent node](./agent-node.md) for authoring exits.
## Journey variables
A guided flow has its own **journey variables** - flow-local memory shared across every node in the flow. Use them to carry data from one step to the next: an `order_id` collected by an early node, a `return_eligible` flag set by an Execute Workflow node, a `pickup_slot` chosen later on.
- **Scope.** Journey variables are local to the flow. They're the flow's working memory, separate from the bot-wide [global memory](../configuration/memory.md) that every agent shares. A Conversational Agent node reads and writes them through its **Variables** capability; an Execute Workflow node can read inputs from them and write its results back.
- **They persist across nodes within a run.** A value written in step one is available in step five - that's what lets a guided agent "remember" what it has collected as it walks the journey.
- **Global memory still works.** If a value needs to be visible to the rest of the bot (not just this flow), use a [global memory](../configuration/memory.md) variable instead. Reach for a journey variable when the data only matters inside this flow.
See [Memory in Nexus agents](../configuration/memory.md) for the full memory model and when to choose local (journey) vs global.
## Step 1: Add a node
In the **Editor** tab, open the node search/palette and pick the node type you want - for an order-return flow, you might add a **Conversational Agent** node to collect the order ID. Drop it onto the canvas. (You can also let the [AI layer](../../index.md) scaffold the node from a description.)
## Step 2: Configure the node
Click the node to open its configuration drawer and give it a clear job. For a Conversational Agent node that means a **Name**, its **Instructions** (the goal/prompt), any **Tools**, **Variables**, and its **Exits** - the outcomes it can finish on. The full walkthrough is on [The Conversational Agent node](./agent-node.md). For an **Execute Workflow** node, pick the workflow to call and map its inputs from your journey variables.
## Step 3: Wire its exits
Drag a **branch** from each exit handle to the node that should run next:
- Wire the success exit (e.g. `eligible`) to the next step in the journey.
- Wire fallback exits (e.g. `not_eligible`, `max_retry`, `on_error`) to a **Transfer to Agent** node, or back to an earlier node to retry.
- Leave any terminal exit unwired so the flow ends cleanly there.
## Step 4: Run and refine
Click **Run** to start a test conversation and walk the path your input takes. If a run goes somewhere unexpected, open the **Logs** tab to see which node fired and which exit it took, then adjust the node's instructions, its exit descriptions, or the branch wiring. When the flow behaves the way you want, click **Publish** to make it live.
> **Tip - test the unhappy paths first.** It's easy to get the success path right. The value of a guided agent is that the *edge cases* also stay consistent. Run the flow with inputs that should hit `not_eligible`, `max_retry`, and `on_error`, and confirm each lands somewhere sensible (usually a Transfer to Agent or a graceful end). See [Testing a guided agent](./testing.md).
---
Continue to: **[The Conversational Agent node](./agent-node.md)** - the node where each step's goal, tools, variables, and exits live.
---
## Guided agents
A **guided agent** runs the exact steps you design, in the same order every time - so nothing is missed and every run stays consistent and auditable. It's the deterministic counterpart to a [conversational agent](../agents/conversational-agents.md): instead of working out each reply on its own from your knowledge, a guided agent follows a flow *you* lay out on a canvas.
Reach for one whenever a task has a fixed procedure that must run the same way every time - order returns, loan applications, KYC checks, booking an appointment. These are the cases where an LLM-driven agent, however well-prompted, is hard to keep on the rails: it can skip a step, ask things out of order, or finish early. A guided agent removes that risk by making the path explicit.
Guided agents live on the same **Agents** page as conversational agents, under their own tab. You create one from the same **Create** picker, then build it on the flow canvas.
Ask the [AI layer](../../ai-layer/index.md) to scaffold a guided agent from a one-line description - it lays out the start, the steps, and the exit branches between them, then waits for your confirmation before saving. Refine it on the canvas afterwards.
## Conversational vs guided - which should I build?
Both are agents you create from the Agents page; the difference is *how* they decide what to do next.
| If the task is… | Build a… | Why |
|---|---|---|
| Open-ended Q&A - answering questions from your knowledge | **Conversational agent** | It works out each reply on its own; no fixed path to enforce. |
| Troubleshooting and support - diagnosing errors, fixing login/device issues, guiding someone to a resolution step by step | **Conversational agent** | The path depends on what the user says; the agent adapts turn by turn. |
| A multi-step procedure that must run the same way every time - order returns, loan applications, KYC checks, booking an appointment | **Guided agent** | The steps and their order are fixed; you want every run consistent and auditable. |
| A regulated or audited process where skipping or reordering a step is unacceptable | **Guided agent** | The flow guarantees each step runs, in order, on every run. |
A useful test: if you'd describe the work as *"it depends on what they ask,"* build a conversational agent. If you'd describe it as *"first do this, then this, then this - every time,"* build a guided agent.
You don't have to choose only one. The two compose: a conversational agent can call a guided agent as a tool when a conversation reaches a part that needs a fixed procedure (for example, a support agent that hands off to a `kyc-verification` guided agent once the user is ready to verify their identity). The conversational agent stays in charge of the open-ended conversation; the guided agent runs the deterministic part and returns control. See [Guided agents as tools](#guided-agents-as-tools) below.
## What's in a guided agent
A guided agent *is* a flow on a canvas - a graph of nodes wired together by **exit branches**. When you open one, you'll see:
- **Start** - the entry node. It carries the **trigger description** (what the guided agent is for / when it runs).
- **Nodes** - the steps. The main node types are:
- **Conversational Agent node** - a focused agent that owns one step of the flow (collect details, confirm, answer a sub-question). It has its own instructions, tools, and exits. This is the workhorse node - see [The Conversational Agent node](agent-node.md).
- **Execute Workflow node** - runs a [workflow](../tools/index.md) (a callable, deterministic skill - an API call, a lookup, a calculation) as a step.
- **Transfer to Agent node** - hands the conversation to a human agent in Inbox.
- **Exit branches** - every node finishes on one of its **exits**, and each exit is wired by a branch to the next node. This is how the flow's order is enforced: a Conversational Agent node that exits on, say, `eligible` goes to one node; on `not_eligible` it goes to another; on `max_retry` or `on_error` it goes somewhere else. The wiring *is* the procedure.
Because the path is drawn out explicitly, a guided agent is easy to reason about and audit: you can look at the canvas and see every route the conversation can take.
For a full tour of the canvas, see [The flow canvas](flow-canvas.md).
## Where guided agents live
Guided agents share the **Agents** page (**AI Agent → Agents**) with conversational agents, but each type has its own tab:
- **Conversational** - your LLM-driven agents. Each row shows a round **avatar**, the agent's name, its trigger description, and a **Live/Draft** status.
- **Guided** - your guided agents. Each row shows a generated **flow icon** (not an avatar), the agent's name, a **Category** tag, and a short description.
The active tab is saved in the URL, so a link to the Guided tab reopens there.
Two things are deliberately different about guided agents in this list:
- **No Live/Draft status.** A flow has no live/draft lifecycle, so the Guided tab has no Status filter - it filters by **Category** and a sort only. (The Conversational tab keeps Status, Category, Updated By, and Last Updated.)
- **A generated icon instead of an avatar**, so you can tell the two types apart at a glance.
To create one, click **Create** in the page header and pick **Guided agent** from the *"What would you like to create?"* picker. (The same picker offers **Conversational agent**.) See [Create an agent](../agents/create.md).
## Guided agents as tools
Every guided agent is **automatically available as a tool** to your conversational agents. There's no toggle to switch on - if a guided agent exists in the bot, your conversational agents can call it.
This is what makes the two types compose cleanly. A conversational agent handles the open-ended conversation, and when it reaches a part that needs a fixed procedure, it calls the relevant guided agent the same way it would call any other tool. The guided agent runs its steps to completion and returns control.
> **Note:** A guided agent is **not** a [workflow](../tools/index.md). "Workflow" is a reserved term for a callable scheduler skill (an API call, a lookup, a job). A guided agent is a conversational journey across nodes - it can *call* a workflow (via an Execute Workflow node), but it is never itself a workflow.
> **Tip - name guided agents by the task.** `order-return`, `kyc-verification`, `book-appointment` read clearly both in the Guided list and when a conversational agent calls one as a tool. A vague name like `flow2` tells the calling agent nothing about when to use it.
## Availability
Guided agents are gated. They appear only on **Nexus** bots that also have the flow-agent capability enabled. When the gate is off, the Agents page behaves exactly as before - no Guided tab, no Guided option in the Create picker.
> **Note:** If you don't see the **Guided** tab on the Agents page, or the Create picker shows only **Conversational agent**, the capability isn't enabled for your account. Talk to your account team to turn it on.
## Read next
- **[Create an agent](../agents/create.md)** - start from the Create picker and open the flow canvas.
- **[The flow canvas](flow-canvas.md)** - the Editor / Execute / Logs tabs, nodes, and exit branches.
- **[The Conversational Agent node](agent-node.md)** - instructions, exits, tools, variables, and first response.
---
## Test a guided agent
A guided agent runs the same steps in the same order every time - which is exactly what makes it testable. Your job when testing is to walk every branch of the flow at least once: confirm each **Conversational Agent node** finishes on the exit you expect, that every exit is wired to the right next node, and that the run holds together end to end.
This page covers the three places you test a guided agent: **Run** on the canvas and the **Execute** tab to drive it, the **Logs** tab to inspect a run, and the **AI Trust Centre** to lock in regression coverage before you ship.
> **Note:** Guided agents have **no Live/Draft status** - there's nothing to "set live." A guided agent runs as soon as it's published and is automatically available as a tool to your conversational agents. So testing isn't a release gate you flip; it's the thing you do every time you change a node, an exit, or a branch. See [Build a guided agent on the canvas](flow-canvas.md).
Ask the [Nexus AI Layer](../../ai-layer/index.md) to drive a guided agent through every branch, then summarise which exits fired and which never matched - a fast way to find a dead branch before you open the Logs yourself.
## Where you test
| Surface | Where it lives | Use it when |
|---|---|---|
| **Run** | The button in the flow canvas header | You want a quick, interactive pass through the flow while you're still editing it. |
| **Execute** | A tab on the flow canvas (Editor / **Execute** / Logs) | You want to drive the agent turn by turn and watch it move from node to node. |
| **Logs** | A tab on the flow canvas | You want to inspect a finished run - which exit each node took, what each branch did, where it stopped. |
| **AI Trust Centre** | [Test & debug → AI Trust Centre](../../test-debug/index.md) | You want durable, repeatable regression coverage that runs on every future change. |
Use them in that order: **Run / Execute** while you build, **Logs** to diagnose, then promote the cases that matter to the **AI Trust Centre** so they run automatically forever after.
## Step 1: Run the agent on the canvas
Open your guided agent from the **Guided** tab on the Agents page (it opens the flow canvas at `/build/flows/`). In the canvas header you'll see **Run** alongside **What's new**, **Publish**, and the **Search for nodes** box.
Click **Run** to start an interactive session against the current state of the flow. The run begins at the **Start** node and follows your wiring: the first **Conversational Agent node** takes control, acts on its instructions, and - when it reaches an outcome - finishes on one of its exits. The exit's **branch** hands control to the next node, and so on until the flow ends or transfers.
This is the fastest way to sanity-check a change. Edit a node, hit **Run**, play the conversation, repeat.
> **Tip - drive it like a real user.** Don't only type the "happy" answer. If a node has a `max_retry` exit described as *"when the user can't decide after 3 attempts,"* test it by being indecisive on purpose. Branches you never exercise are branches you never verified.
## Step 2: Drive it turn by turn from the Execute tab
Switch to the **Execute** tab on the canvas. This is the dedicated harness for stepping the flow as an end user: you send a message, the agent responds, control moves to the next node when the current one finishes on an exit, and you keep going.
As you converse, confirm three things on each step:
1. **The right node has control.** A node only takes over when a branch from the previous node points to it. If the wrong node speaks, the wiring upstream is off.
2. **The node finished on the exit you expected.** A Conversational Agent node ends on one of its exits - for example an intent exit (`vpf`, `nps`), a `max_retry` exit, or `on_error`. The exit it picks is driven by its **Instructions** and the natural-language **description** on each exit.
3. **The branch sent you to the right place.** Each exit is wired by a branch to a next node. Walk the conversation down each branch at least once.
Run through the flow several times, taking a different path each time, until you've covered every branch - including `max_retry` and `on_error`.
## Step 3: Inspect a run in the Logs tab
When a run does something you didn't expect - wrong node took over, the flow stopped early, an exit never matched - open the **Logs** tab. Logs give you the run's history so you can see *why* control moved the way it did, node by node.
Read the log top to bottom and ask:
- **Which exit did each node finish on?** If a node you expected to take the `refund` exit took `max_retry` instead, its **Instructions** or that exit's **description** isn't steering the model the way you think. Sharpen them (see [Configure a Conversational Agent node](agent-node.md)).
- **Did a branch go nowhere?** If a node finished on an exit but the run stopped there, that exit has no branch wired to a next node. Go back to the **Editor** tab and connect it.
- **Did `on_error` fire?** An `on_error` exit means the node hit a failure (a tool error, an unhandled condition). Follow that branch and confirm it lands somewhere graceful - a retry, a `Transfer to Agent` node, or a clean message - not a dead end.
> **Tip - match Logs against the graph.** Keep the **Editor** tab's node graph in mind as you read Logs. The exit labels in the log are the same labels you see on the node's output handles in the canvas - tracing one against the other is the quickest way to spot a misrouted branch.
## Step 4: Promote durable cases to the AI Trust Centre
Run / Execute / Logs are for the loop you run *while building*. They don't persist - close the tab and the run is gone. For coverage that survives every future edit, promote the conversations that matter into the **[AI Trust Centre](../../test-debug/index.md)**.
The Trust Centre is the durable, dataset-driven side of testing. Capture a guided-agent conversation as a **test case**, add it to a dataset, and it runs automatically on every future change - so a branch you wired correctly today can't silently break next month. See the **[Testing Lab](../../test-debug/trust-centre/testing-lab.md)** for capturing and curating cases, and the [Test & debug overview](../../test-debug/index.md) for the full picture.
A good regression set for a guided agent covers, at minimum:
- **One case per branch.** Every exit on every Conversational Agent node should have at least one case that drives the conversation down it - including `max_retry` and `on_error`.
- **The unhappy paths.** Indecisive users, invalid inputs, mid-flow topic changes. These are where consistency breaks.
- **The full journey end to end.** A single case that walks the whole flow from Start to its terminal node, so you catch wiring regressions across the whole graph at once.
> **Tip - guided agents are tools too.** Because a guided agent is automatically available as a tool to your conversational agents, also test it *from the calling side*: open the conversational agent that invokes it and confirm it hands off to the guided agent at the right moment. See [Conversational agents](../agents/conversational-agents.md).
## Common pitfalls
| Symptom | Likely cause | Fix |
|---|---|---|
| A node never takes the exit you expect | The exit's **description** is too vague for the model to match against (e.g. "if relevant" instead of "if the intent is a refund request"). | Rewrite the exit description in plain, specific language; tighten the node's **Instructions**. See [agent-node.md](agent-node.md). |
| The run stops dead after a node | An exit was left **unwired** - it has no branch to a next node. | Open the **Editor** tab and connect the exit's output handle to the next node. |
| Two exits both seem to match | Overlapping exit descriptions on the same node. | Sharpen the boundary between them, or merge them into one exit. |
| `on_error` fires unexpectedly | A tool the node calls is failing, or the node hit an unhandled condition. | Check the failing step in **Logs**; fix the tool or add handling, and make sure the `on_error` branch lands somewhere graceful. |
| The first node says nothing on entry | **First response** is off (the default) - the node acts on its instructions without a canned opener. | If you want a spoken opening when control reaches the node, turn **First response** on. See [agent-node.md](agent-node.md#first-response). |
| It passes once, then behaves differently | The agent layer is stochastic - a single pass doesn't prove a branch is reliable. | Run the same path more than once; promote it to a Trust Centre dataset so it's checked every time. |
> **Note:** Don't confuse a *vague exit description* with a *missing branch*. A vague description means the node finishes on the wrong exit (Logs shows it picking the wrong label); a missing branch means the node finishes on the **right** exit but the run stops because that exit isn't wired (Logs shows it ending after a node that should have continued). The first is fixed in the node config, the second in the canvas.
## Best practices
- **Walk every branch before you publish.** A guided agent's whole value is determinism - but only the branches you've actually run are the ones you've verified.
- **Test the retry and error paths on purpose.** `max_retry` and `on_error` are where real conversations go sideways. Be indecisive; feed bad input; make a tool fail if you can.
- **Read Logs against the graph.** The exit labels in Logs map one-to-one to the output handles in the Editor - trace them together to pin a misroute.
- **Promote anything that matters to the Trust Centre.** Run/Execute is throwaway; a Trust Centre dataset is the only test that runs again next month.
- **Re-test after every wiring change.** Moving one branch can reroute a whole journey. Don't trust a flow you edited but didn't re-run.
Continue to: **[Guided agents best practices](best-practices.md)**.
---
## AI agents
A Nexus agent is a small team of specialised agents working together, with their behaviour shaped by a shared Configuration, running on the Nexus engine. The engine adds platform-enforced refinements (two-stage routing, automatic step execution, parent-child agent triggers with auto-return, history compaction, structured traces) and authoring surfaces like Routing Logic, Widget Builder, the AI Trust Centre, and versioned configuration. See [What the Nexus engine does for you](#what-the-nexus-engine-does-for-you) below for the details.
## The building blocks
Specialised agents now come in two types:
- **Conversational agents** - LLM-driven specialists that work out each reply on their own from your instructions and knowledge. Best for open-ended Q&A, troubleshooting, and anything where the path depends on what the user says.
- **Guided agents** - deterministic agents that run the exact steps you lay out on a flow canvas, in the same order every time. Best for fixed procedures that must run consistently and auditably - order returns, KYC checks, booking flows. See [Guided agents](guided-agents/index.md).
### Configuration
**Configuration is project-level** - the settings you define here apply to **all your agents**, conversational and guided alike. It's where you set persona, identity, conversation rules, routing logic, memory, fallback, lifecycle hooks, AI safety, and voice. At runtime:
- Every incoming message is read.
- Routing decides whether to answer directly or hand off to one of your agents.
- Your persona, identity, and rules shape the reply.
- Tools (workflows, knowledge base lookups, escalations) are called when data is needed or an action must be taken.
You set this up in **AI Agent → Configuration**. See [Configuration](configuration/index.md) for the full tour.
### Agents
Agents are specialists you design for one job each - an **order-status agent** that answers "Where's my order?", a **demo-booking agent** that helps users pick a slot, a **billing agent** that handles refunds and invoices. Every agent inherits the project-level Configuration above; on top of that, agents come in two types:
- **Conversational agents** - LLM-driven specialists that work out each reply on their own. ([guide](agents/conversational-agents.md))
- **Guided agents** - deterministic agents that run a fixed flow you lay out on a canvas. ([guide](guided-agents/index.md))
You create either type from the same **Create** picker - start at [Create an agent](agents/create.md). Each agent can also follow its own rules in addition to the shared Configuration's, though you'll rarely need that on day one.
Routing decides *when* to hand off to an agent. It reads each agent's **Trigger** (the natural-language description at the top of the agent's profile) as the primary routing signal. You can *optionally* add [Routing Logic](configuration/routing-logic.md) rules to make specific handoffs deterministic when Triggers alone aren't precise enough. Once an agent takes over, it owns the conversation until control returns.
You manage agents in **AI Agent → Agents**.
### Global components
These are reusable pieces - shared prompts, policy text, tone snippets - that you can pull into any agent. Define them once, reuse them everywhere. Update them in one place and every agent using them gets the change.
You manage these in **AI Agent → Global Components**.
### Tools
Tools are the actions an agent can take in the real world: call a workflow, search a knowledge base, escalate to a human, transfer a call. You define them once and any agent in the bot can use them - and they can be called directly at the Configuration level too. Attach a tool to a specific agent when it belongs to that agent's job; that also helps route a topic to the right place.
## How routing decides what to do
```mermaid
flowchart TD
M["User message"] --> R{"Routing - reads each agent's Triggerand your optional Routing Logic rules"}
R -->|best-matching agent| A["Hand off to an agent"]
R -->|no agent needed| D["Answer directly"]
R -->|needs data or an action| T["Call a tool"]
A --> Resp["Reply, shaped by Configuration"]
D --> Resp
T --> Resp
```
When a user sends a message, one of three things happens: the message is answered directly, the conversation is handed off to one of your **agents** (an order-status agent, a billing agent, a demo-booking agent, etc.), or a **tool** is called. The primary input is:
- **Each agent's Trigger** - the natural-language description at the top of every agent's profile that says *when* the agent should activate ("When the user wants to book or schedule a test ride…"). Routing reads every Trigger and picks the best match.
For simple bots with clearly distinct Triggers, that's all you need - agent routing works out of the box. You can *optionally* add **Routing Logic rules** (plain-English overrides like "If the user mentions billing or refunds, hand off to `@billing-agent`") when you want a deterministic override on top of trigger-based routing.
Tools work the same way: any tool can be called directly, using each tool's description as a routing signal. Attach a tool to a specific agent when it belongs to that agent's job - that also helps routing.
## Where to find each surface in the studio
| Want to… | Go to |
|---|---|
| Edit Configuration (project-level - applies to all your agents) | **AI Agent → Configuration** |
| Add or edit agents | **AI Agent → Agents** |
| Manage shared snippets | **AI Agent → Global Components** |
| Build a custom widget | **AI Agent → Widget Builder** |
| Test your agent | **AI Trust Centre** (top-level menu item) |
## A typical build flow
If you're starting fresh, work in this order:
1. **Set up Configuration** - project-level persona, identity, welcome, fallback that apply to every agent. ([guide](configuration/index.md))
2. **Create an agent** for each distinct task (order status, demo booking, billing) - conversational or guided. ([guide](agents/create.md))
3. **Write Routing Logic rules** when you want a topic to *always* route to a specific agent. ([guide](configuration/routing-logic.md))
4. **Add tools** to whichever agents need them.
5. **Test interactively** in the Playground (▶ on each agent), then **regression-test** with datasets in the AI Trust Centre. ([guide](../test-debug/index.md))
6. **Build widgets** if you need custom UI. ([guide](../widget-builder/index.md))
7. **Deploy** - connect your agent to channels (web, WhatsApp, voice, …) and publish it. ([Channels & Deploy](../channelConfiguration/overview.md))
8. **Monitor** - track conversations, performance, and quality once it's live. ([Analytics](../analyze/analyseintro.md))
Steps 1-6 live in **Harness**; deploy and monitor are handled by the sibling **Channels & Deploy** and **Analytics** products - the build → test → deploy → monitor lifecycle spans the product rail, not just this section.
```mermaid
flowchart LR
B["Build(Harness)"] --> T["Test(AI Trust Centre)"]
T --> D["Deploy(Channels & Deploy)"]
D --> Mo["Monitor(Analytics)"]
Mo -. insights .-> B
```
## What the Nexus engine does for you
These are the platform-enforced behaviours you get out of the box, on top of the specialised-agents + shared-Configuration + tools model.
| Area | Nexus change | Why it matters |
|---|---|---|
| **Routing** | Two-stage LLM call - a small **Context Expert** picks the agent from each agent's **Trigger description** only, then a **Conversation Agent** runs that agent's instructions + tools. | Faster routing (smaller Stage 1 model), narrower Stage 2 prompt, fewer wrong-tool calls. |
| **Continuity** | The platform enforces a fixed continuity rule every turn - keep on the same agent unless the user has clearly switched topics. | Fewer mid-flow drop-offs without writing defensive "stay here" logic. |
| **Numbered steps** | If your **Agent instructions** list `Step 1: / Step 2: …`, the platform auto-injects sequential-execution rules: one step per turn, with step progress tracked automatically. | Multi-step procedures stay on track without per-flow boilerplate. |
| **Parent-child agent triggers** | A parent agent can call a child agent: the platform snapshots the parent's state, runs the child, and auto-restores the parent when the child completes. **1 level deep.** | Reusable sub-tasks (verify identity, capture payment) callable from any parent without writing return logic. |
| **Conversation history** | Once history exceeds ~15 messages / ~10K characters, older turns are automatically summarised; the last 2 user turns stay verbatim. | Long support conversations don't blow context; recent turns stay verbatim. |
| **Tool failure** | Platform rule: don't retry the same tool. Return the error as the tool result so the LLM phrases a recovery message. | Predictable failure UX; no silent retries. |
| **Execution trace** | Every turn stores a structured `executionTrace` - tool calls + results, memory writes, intent classifications, the Context Expert decision. | Testing lab and Copilot Debug share one underlying record. A buggy production conversation becomes a regression test in one click. |
| **Routing Logic surface** | New sub-page under Configuration (**Configuration → Routing logic**) where you write *optional* plain-English rules ("if billing → @billing-agent"). | Deterministic handoff when you want it; routing falls back to each agent's Trigger when you don't. |
| **Widget Builder** | New top-level surface for designing custom in-conversation UI (forms, pickers, multi-step wizards). | Custom UI without channel-specific code. |
| **AI Trust Centre** | New top-level menu - Testing lab + Evaluators & Rules (Quality / Safety scoring with thresholds). | Durable regression coverage and automated scoring. |
| **Versioned configuration** | Every Configuration change is versioned with history. | Roll back; review behaviour shifts over time. |
| **`@`-mentions in prompts** | Type `@` in any prompt field to insert a live reference to an agent, workflow, tool, or rich-media item. Chips stay linked through renames. | Prompts don't go stale when you rename a target. |
| **Welcome / Fallback options** | Welcome supports Instruct, Send message, or any welcome workflow you've defined (each workflow shows up as its own option). Fallback supports Instruct + a retry count for validation failures. | Cleaner UX; workflows attach as options instead of via a generic "Trigger a flow" item. |
## Best practices
- **Start small.** Just your Configuration with no extra agents is a perfectly good starting point. Add agents only when you have clearly separable tasks.
- **Name agents by the task they own.** `order-status-agent`, `demo-booking-agent`, `billing-agent` beat `agent2`. Sharp names lead to sharp routing.
- **Don't build a "general" agent.** A general-purpose agent is a sign routing isn't doing its job. Keep each agent focused on one task.
- **Write rules in plain English, then test.** It's easier to refine wording after seeing how routing interprets it than to engineer a perfect rule upfront.
- **Use Global Components for anything you copy more than once.** Policy text, brand voice instructions, common disclaimers - define once, reuse.
- **Test before every release.** Even small wording changes to identity or rules can shift behavior. Regression-test with a saved dataset before you ship.
Continue to: **[Configuration](configuration/index.md)**.
---
## Nexus Edge Tools
Nexus Edge tools run **on the end-user's desktop** via the NexusEdge desktop client, not in the cloud. When the agent calls an edge tool the runtime sends a request down the chat stream to the desktop, which executes the tool locally (file access, printers, browsers, system APIs) and posts the result back.
## Who it's for
Builders deploying Nexus agents on the NexusEdge desktop client — IT helpdesk, device support, and any use-case where the agent needs to interact with hardware or the local machine.
## Tool types: read-only vs. mutating
Every edge tool is classified as either **read-only** or **mutating** in its definition.
| Type | Examples | Widget behaviour |
|---|---|---|
| **Read-only** | Get printers, Print queue, System info | Runs immediately, no prompt |
| **Mutating** | Cancel print job, Restart spooler, Set default printer | Shows an **Allow / Deny** gate before running |
You can see the classification in **Tools → Add Tool → Nexus EDGE → Device**: mutating tools are labelled "Mutating — requires user Allow" in the picker.
## Approval gate for mutating tools
When the agent calls a mutating edge tool, the widget pauses and shows the user an **Allow / Deny** prompt. This gives the user explicit control over actions that change state on their machine.
How the timing works:
1. **Server starts a 10-minute decision window.** The LLM turn is paused — the user can take their time.
2. **User clicks Allow.** The widget sends `edge.tool.approved` immediately. The server resets the timer to the tool's normal execution timeout (typically a few seconds), so deliberation time does not count against the tool run.
3. **User clicks Deny.** The tool resolves with a denial error and the agent continues the conversation.
4. **No response within 10 min.** The tool times out and the agent continues with a `tool_timeout` error.
If a user needs more than 10 minutes to decide (e.g. they stepped away), they can ask the agent to retry — the agent will issue a new tool call and restart the gate.
## Parallel dispatch
When an LLM turn calls multiple edge tools at once, the runtime sends **all tool-call events to the desktop simultaneously** (fan-out), then waits for all results in parallel. Previously tools were dispatched one-by-one.
Practical effect: a turn that calls three read-only tools (printers + print queue + spooler health) now takes as long as the slowest single tool instead of the sum of all three.
## Printer test page
The `printer.testPrint` edge tool generates a diagnostic test page. As of this release it sends **plain text** (rendered via `texttopdf → cups-raster`) instead of PostScript. This ensures compatibility with AirPrint-only printers (Brother, some HP models) that do not declare PostScript support in their PPD and previously silently rejected the `.ps` file.
## Screenshots
---
## Escalation tools - Escalate to Agent & Transfer Call
When your agent can't resolve a request, it should hand off to a human cleanly. Nexus ships two purpose-built escalation tools:
- **Escalate to Agent** - for chat conversations. Routes the user to a human agent in Inbox.
- **Transfer Call** - for voice conversations. Forwards the call to a human agent or SIP extension.
Configure both in **AI Agent → Tools → Add Tool**.
## Why have a dedicated escalation tool?
You *could* trigger a workflow that does the handoff. But a dedicated tool gets you:
- A **standardized config** for collecting customer info before handoff.
- **Priority and assignment rules** built in.
- A **clear LLM contract** - the agent knows "this is the escalation path", not "one of seven workflows that might do something escalation-shaped."
Use the dedicated tool unless you have a very specific reason not to.
---
## Escalate to Agent (chat)
This is the right tool when the user asks for a human, the agent recognizes a complex case it can't solve, or a Routing Logic rule sends them to support.
### Step 1: Add the tool
**AI Agent → Tools → Add Tool → Escalate to Agent**.
The drawer opens with **Settings**, **Chat Escalation**, and **Test** tabs.
### Step 2: Settings - name and description
Name: something like `escalateToSupport`, `transferToBilling`, or `talkToHuman`.
Description: tell the LLM exactly when to call this. Example:
> "Hand the conversation to a human support agent. Use this when the user explicitly asks for a human, when you've failed to resolve their issue after two attempts, or when they express strong frustration. Do not use this for billing questions - use the **escalateToBilling** tool instead."
### Step 3: Chat Escalation tab
This is where you configure the handoff itself.
#### Priority and assignment
| Setting | Purpose |
|---|---|
| **Default priority** | `low`, `medium`, or `high`. Sets the ticket priority on creation. |
| **Queue ID** | The Inbox queue this escalation lands in. |
| **Tags** | Tags applied to the resulting ticket - useful for routing and reporting. |
| **Assignment strategy** | `round-robin`, `least-busy`, or `specific-group`. How the ticket is assigned. |
| **Assign to group** | The specific Inbox group when strategy is `specific-group`. |
**Best practices:**
- Set **priority** based on the *trigger*, not on optimism. Frustrated users escalating after multiple failed attempts are usually `high` - not `medium` "to be safe."
- **Use specific-group** assignment for domain escalations (billing → billing group, technical → tier-2 engineering). Round-robin works for general support.
- **Tag every escalation tool distinctly.** Reporting later (e.g. "how often does the bot fail at billing?") is impossible without good tags.
#### Pre-handoff data collection
| Setting | Effect |
|---|---|
| **Collect name** | Agent asks for the user's name before escalating (if not already known). |
| **Collect mobile** | Same for mobile number. |
| **Collect email** | Same for email. |
| **Require reason** | The agent must capture *why* the user is escalating before handing off. |
| **Require summary** | The agent generates a short summary of the conversation for the human to read. |
The human agent in Inbox sees this info immediately on pickup - no "what's going on?" first message.
**Best practices:**
- **Always require summary.** Saves the human agent 30 seconds per ticket. Multiplied over a year, that's hours.
- **Only collect contact info when needed.** If the user is already authenticated and you have their email, don't ask again. The agent should be aware of session context.
- **Require reason for non-obvious escalations.** "User asked for a human" is enough context. "User is frustrated about \" needs a reason.
#### Custom fields
Add structured fields the agent should collect before escalating. Each custom field has:
- **Name** (e.g. `orderId`)
- **Type** (`string`, `number`, `boolean`)
- **Description** (LLM uses this to know what to ask for)
- **Required** (yes/no)
Use this for domain-specific data: order ID for shipping issues, account ID for billing, error code for technical bugs.
#### Escalation message
The message shown to the user *as the handoff happens*. Default is something neutral like "Connecting you to an agent now…". Customize it for tone or to set expectations ("A specialist will join in under two minutes…").
### Step 4: Test
The Test tab simulates the escalation. You won't actually create a real ticket - you'll see the structured payload that *would* be created and any prompts the agent would say.
### Step 5: Wire it in
Most teams want escalation to be deterministic, not at the LLM's discretion. Add a Routing Logic rule:
> "If the user asks for a human agent, says 'agent' or 'human', or expresses strong frustration (e.g. 'this is unacceptable', 'I want to speak to someone'), call the **escalateToSupport** tool immediately. Do not try to resolve the issue first."
---
## Transfer Call (voice)
For voice channels - when the user is on a call and needs a human.
### Step 1: Add the tool
**AI Agent → Tools → Add Tool → Transfer Call**.
The drawer opens with **Settings**, **Voice Transfer**, and **Test** tabs.
### Step 2: Settings
Name: `transferToHuman`, `transferToBillingAgent`, or similar.
Description: explicit, like in the chat case. The LLM uses this to decide.
### Step 3: Voice Transfer tab
#### Action type
Pick one:
| Action | What it does |
|---|---|
| **Forward call** | Forward the call to a phone number (PSTN). |
| **SIP transfer** | Transfer via SIP to an internal extension. |
Forward is the right default. Use SIP when integrating with on-premise PBX or specialist routing systems.
#### Forward call settings
- **Forward number** - the destination phone number.
- **Caller line identity** - what the caller ID shows on the receiving end (typically the user's number, sometimes your own).
#### SIP transfer settings
- **SIP extension** - the SIP URI to transfer to.
- **Custom SIP headers** - key/value pairs for SIP-level metadata (e.g. customer ID, conversation summary).
Custom headers are how you pass conversation context into your contact-center stack so the receiving agent has it on pickup.
#### Recording action
What happens to the call recording when the transfer fires:
| Action | Meaning |
|---|---|
| **Continue** | Keep recording through the human portion. Default for compliance setups. |
| **Pause** | Pause recording during the human portion (resume after). |
| **Stop** | End recording at transfer. |
Pick based on your privacy/compliance posture. When in doubt, talk to legal.
#### Announcement
A spoken message played to the user *just before* the transfer ("Connecting you now…"). Customize the wording and tone - voice users notice handoff awkwardness more than chat users.
### Step 4: Test
The Test tab simulates the transfer - you'll see the call-control instructions that would fire.
### Step 5: Wire it in
Same pattern as chat - add a Routing Logic rule for explicit triggers:
> "If the user says 'agent', 'human', 'representative', or asks to speak to someone, call the **transferToHuman** tool immediately."
---
## Best practices for both
- **Always have an escalation tool.** A bot with no escape hatch is a bad bot.
- **Make escalation deterministic with Routing Logic.** Don't leave "user asked for a human" up to the LLM's interpretation.
- **Collect just enough info upfront.** Saves human agent time, but don't grill the user with five questions before handing off - frustration goes up.
- **Tag escalations precisely.** Reporting on "where does the bot fail?" depends on good tags.
- **Test the path.** Walk through an escalation end-to-end yourself in the **Playground** (▶ on any agent). The first time you actually try it shouldn't be in production.
- **Voice and chat behave differently.** Don't assume what's right for chat is right for voice. Voice users are less patient with announcements and pre-handoff questions.
## Common pitfalls
| Symptom | Likely cause |
|---|---|
| Bot escalates too eagerly | Description is too broad, or no Routing Logic rule defines the trigger. Tighten both. |
| Bot never escalates | LLM doesn't see the trigger. Add a Routing Logic rule and use words real users say ("human", "agent", "representative"). |
| Human agent has no context on pickup | "Require summary" not enabled, or no tags on the escalation. Fix both. |
| Wrong queue / group | Assignment strategy or queue ID is misconfigured. Test in non-prod first. |
| Voice transfer drops the call | SIP headers / forward number formatting issue. Test against your PBX before going live. |
## Legacy reference
The legacy [Transfer to live agent](../../../platform_concepts/AIAgent/transfer-live-agent.md) doc covers escalation on the legacy platform. Nexus's Escalate to Agent tool is the equivalent and adds richer config.
---
## Tools - Overview
**Tools** are the actions your agent can take in the real world: run a workflow, search a knowledge base, escalate to a human, or transfer a call. Without tools, your agent can only talk. With tools, it can *do*.
This section walks you through every tool type that's live today, when to use each, and how to configure them.
## Where to find tools
In your bot, go to **AI Agent → Tools**.
You'll land on the Tools list page - one place that shows every tool defined for this bot. From here you can:
- **See every tool** at a glance, with its type, name, and description.
- **Filter by type** (Workflow, Knowledge Base, Escalate to Agent, Transfer Call, API, Skill, Function).
- **Add a new tool** via the **Add Tool** button.
- **Edit a tool** by clicking its row - the configuration drawer opens on the right.
The page paginates 50 tools at a time. Searching by name works as you'd expect.
## What tool types are available today?
Click **Add Tool** and you'll see a picker with three categories:
### Core Built-in (live now)
| Tool | What it does |
|---|---|
| **Workflow** | Connect to an existing workflow you've built in the visual flow editor. Run multi-step business logic, integrations, or backend work. |
| **Knowledge Base** | Let your agent answer from documents and FAQs. Configurable confidence threshold, filters, history context, and result formatting. |
| **Escalate to Agent** | Route the chat to a human agent in Inbox. Optionally collect name/email/phone first, set priority, assign to a group. |
| **Transfer Call** | Forward an in-progress voice call to a human agent or SIP extension. |
### Custom & MCP (coming soon)
- **Connect MCP Server** - connect any custom data source or API via Model Context Protocol.
- **HTTP Webhook** - trigger an external REST endpoint.
- **Custom Function** - write a JS snippet for the LLM to execute.
### Integrations (coming soon)
- **Slack**, **PostgreSQL**, **Google Calendar**.
Coming-soon tools render in the picker but aren't clickable yet.
## Anatomy of a tool
Every tool - regardless of type - has the same top-level shape:
| Field | Why it matters |
|---|---|
| **Name** | What you (and the LLM) refer to the tool as. |
| **Description** | A plain-English explanation of what the tool does. The LLM reads this to decide *when to call the tool*. This is the single most important field on the page. |
| **Type** | The execution type (Workflow, Knowledge Base, etc.). Set when you create the tool; not changed afterwards. |
| **Input schema** | The arguments the tool expects. The LLM extracts these from the conversation. |
| **Output schema** | The shape the tool returns. The agent reads these values to continue the conversation. |
| **Type-specific config** | Workflow target, KB filters, escalation rules, transfer settings - depending on type. |
### Why description is the most important field
The LLM doesn't read your code. It reads your tool's name and description and decides whether to call it. A vague description gets you vague behavior:
> ❌ "Check stuff."
A precise description gets you reliable behavior:
> ✅ "Look up an order's status by order ID. Returns the current shipment state, tracking number, and ETA. Use this when the user asks about an order they've already placed - not for new orders."
The same trap applies to the **name + description together** - a goal-shaped name and a description that restates the name teach the LLM nothing:
> ❌ Name `bookAppointment` · Description "Book an appointment."
State plainly what each input and output means, and *when* to call it:
> ✅ Name `bookAppointment` · Description "Reserve an open slot for the user. Needs the service type and a preferred date; returns the confirmed slot and a booking reference. Call this only after the user has chosen a date - use `@AppointmentDateValidator` first to confirm it's available."
Spend time on tool descriptions. It pays off every conversation.
## Tabs you'll see in the configuration drawer
When you open or create a tool, the right-side drawer shows several tabs depending on the type:
| Tab | When you'll see it | Purpose |
|---|---|---|
| **Settings** | Always | Name, description, input/output schema. |
| **Actions** | Workflow tools | Pick the target workflow. |
| **KB Config** | Knowledge Base tools | Confidence, filters, history, result formatting. |
| **Chat Escalation** | Escalate to Agent | Priority, assignment, fields to collect. |
| **Voice Transfer** | Transfer Call | Forward number, SIP, recording behavior. |
| **Mocks** | Workflow tools | Stub responses for testing without firing the real workflow. |
| **Test** | Always | Run the tool with sample inputs, see the output. |
Always **Test** before saving. The Test tab lets you call the tool with sample arguments and inspect what comes back - saves you a debugging round-trip later.
## A typical "add a tool" workflow
1. Open **AI Agent → Tools**.
2. Click **Add Tool**.
3. Pick the tool type.
4. Fill in **Name** and **Description**. Be specific about *when* the LLM should call this tool.
5. Configure the type-specific tab (target workflow, KB settings, escalation rules, etc.).
6. Define the **input schema** (what arguments the tool needs).
7. Open the **Test** tab and run the tool against a sample input. Confirm it returns what you expect.
8. Save.
9. The tool is now available to any agent in this bot. It is picked up automatically based on its name and description.
## How agents pick a tool
Each agent sees the list of tools available to it, plus each tool's name, description, and input schema. When a user message arrives:
1. Decides whether *any* tool fits.
2. If yes, picks the best-fit tool by description.
3. Extracts the required input arguments from the conversation.
4. Calls the tool.
5. Reads the output and continues the conversation.
You influence step 1-3 with **descriptions** and **routing logic**. You influence step 4-5 with **input/output schema design**.
## Referencing tools in prompts
When you mention a tool in an agent's instructions, how you phrase it matters. The model takes your wording literally.
**Name tools by their goal, then reference them by that name.** A goal-shaped `@` reference tells the model what the tool is for at the point of use. Opaque names force it to guess.
> ❌ `@wf1`, `@process2`, `@handler_final`
> ✅ `@PhoneNumberValidator`, `@AppointmentDateValidator`
**Say "call" the tool - not "execute" or "run" it.** "Call" is the action the model performs; "execute"/"run" reads as prose and is easier to ignore.
> ❌ "Execute @FetchOrderDetails to get the order."
> ✅ "Call `@FetchOrderDetails` with the order ID."
**Rich media and quick replies are tool calls, not descriptions.** Don't ask the model to "display" cards or "show" quick replies in prose - it'll narrate the intent instead of firing the tool. Name the tool and call it.
> ❌ "Display the pending items using `@cards-pending-orders`."
> ✅ "Call `@cards-pending-orders` to show the pending orders."
> ❌ "Show quick replies asking the user to pick a delivery slot."
> ✅ "Call `@quick_replies` and ask 'Pick a delivery slot.' with options: Morning / Evening."
## Best practices (high-level)
These apply to every tool type. Type-specific tips live on their own pages.
- **Write descriptions for the LLM, not for humans.** "What does this tool do, and when should you call it?" - answer both, in plain English, in the description.
- **Keep input schemas minimal.** Every input you ask for is one more thing the LLM has to extract correctly. Cut fields that aren't actually needed.
- **Test every tool in isolation** before wiring it into routing logic.
- **Name tools consistently.** `getOrderStatus`, `updateAddress`, `escalateToBilling` - verb-first, scoped to the domain. Avoid `tool1`, `helper`, etc.
- **Use Routing Logic to make critical handoffs deterministic.** "If the user mentions billing, call the `getInvoice` tool" beats hoping the LLM figures it out.
- **One tool, one job.** A tool that does five things is harder for the LLM to use correctly than five focused tools.
## Read next
- **[Workflow tool](workflows.md)** - connect a flow as a tool.
- **[Knowledge Base tool](knowledge-base.md)** - answer from documents and FAQs.
- **[Escalation tools](escalation.md)** - Escalate to Agent (chat) and Transfer Call (voice).
- **[Best Practices](../../best-practices/tools.md)** - patterns that consistently produce good agents.
---
## Knowledge Base tool
The **Knowledge Base tool** lets your agent answer from your documents and FAQs. When the user asks a question your KB can answer, the agent searches it, picks the best matches, and composes a reply grounded in the source content.
This is the right tool whenever the answer lives in content you've already authored - policies, product docs, internal wikis, FAQs.
Ask the [Nexus AI Layer](../../ai-layer/index.md) to index a website or document set into your knowledge base - and to check why a specific question isn't matching once it's indexed.
## Before you start
Make sure your knowledge base actually has content. Upload your documents and FAQs in the Knowledge Hub before connecting the KB tool. The tool searches whatever's there at runtime.
## Step 1: Add the tool
In your bot, go to **AI Agent → Tools → Add Tool → Knowledge Base**. The configuration drawer opens with three tabs: **Settings**, **KB Config**, and **Test**.
## Step 2: Settings - name and description
Like every tool, KB tools start with **Name** and **Description**.
Good description:
> "Search Acme's product documentation and FAQs. Use this for any product feature question, troubleshooting, pricing tier comparison, or how-to. Do not use this for billing or order-status questions - those have dedicated tools."
The LLM reads this to decide when to fire the KB lookup vs another tool. Be explicit about both *when to use it* and *when not to*.
## Step 3: KB Config - the meaningful settings
Switch to the **KB Config** tab. This is where most of the work lives.
### Filters
Restrict the search to a subset of your KB:
- **Tags** - only search documents tagged with any of these.
- **Source** - only search documents from a specific source/connector.
- **Document IDs** - pin to a specific list of documents.
Use filters to scope a tool to a domain. If you have separate KB tools for "Product Docs" and "Internal Policies", give each its own tag filter so the LLM doesn't pull policy text into a product answer.
**Tip:** the **`_inputOverrides`** option lets you decide whether each filter is set by the LLM at runtime (`source: "llm"`) or fixed in the config (`source: "fixed"`). Fix filters when you want guaranteed scoping; let the LLM decide when scoping depends on the user's question.
### Confidence and result tuning
| Setting | What it does | Typical value |
|---|---|---|
| **Confidence** | The minimum match score (0-1) for a result to be used. Below this, results are dropped. | 0.6-0.8 |
| **Search size** | How many top results to retrieve from the KB. | 5-10 |
| **Results per document** | Cap on how many chunks to use from a single document - prevents one big doc from drowning out others. | 1-3 |
**Best practices:**
- **Don't crank confidence to 0.9+.** You'll get fewer hits and the agent will say "I don't know" too often. Start at 0.6, raise it only if you're seeing irrelevant matches.
- **More search results ≠ better answers.** 5 well-chosen chunks beats 20 noisy ones.
- **`Results per document` = 1-3** is usually right. Higher only when your docs have very long sections that genuinely span multiple ideas.
### Result formatting
| Setting | Effect |
|---|---|
| **Show links** | Include source links in the agent's reply (so the user can read the full doc). |
| **Show page numbers** | Include page numbers for PDFs / paginated sources. |
| **Show confidence** | Display the match score next to each citation. |
| **Rich media** | Render images / videos / formatted blocks pulled from the source. |
Show links when your audience benefits from reading the source themselves (B2B support, technical docs). Hide them when you want a clean conversational reply (consumer chat, voice).
### Conversation history
| Setting | Effect |
|---|---|
| **Use conversation history** | Pass prior turns into the KB query so context-dependent questions ("and what about the Pro tier?") work. |
| **History turns** | How many prior turns to include. |
Turn this on for any conversational KB tool. Without it, follow-up questions fall flat.
### Result instructions
The **result instructions** field is a freeform prompt fragment that tells the LLM how to use the search results. Examples:
- "Always cite the document title in your reply."
- "If the user asks about pricing, also mention that pricing tiers are subject to annual contract changes."
- "Keep replies under three sentences unless the user asks for detail."
This is your hook for shaping the answer style without rewriting your bot's identity.
### Cached answers (advanced)
The **Use cached answers** option hits a v2 endpoint with caching enabled. If a pre-computed answer above the confidence threshold exists, it's sent to the user directly - skipping the LLM composition step. This is faster and cheaper but less flexible.
Turn it on for high-volume FAQ bots where a known canonical answer is what you want. Leave it off when you want the LLM to phrase the answer in context.
## Step 4: Define input schema
KB tools have a fixed input shape - typically just `{ query: string }`. You can edit the **query description** to bias what the LLM extracts:
> "The user's natural-language question, rephrased into a clear, standalone search query."
This nudges the LLM to clean up vague questions before searching.
## Step 5: Test before saving
Switch to the **Test** tab. Provide a sample query (think of a real user question). Run it.
You'll see:
- The retrieved chunks with their confidence scores.
- The composed reply.
- Whether the cached-answer path fired (if enabled).
Try several queries - including obvious ones, edge cases, and things you *know* aren't in your KB (the agent should say it doesn't know, not hallucinate).
## Step 6: Save
Click **Save**. The KB tool is now available to any agent in this bot.
## Step 7: Tell the agent when to use it
KB tools can be invoked implicitly (the LLM picks them up via the description) or explicitly (Routing Logic). For high-quality bots, do both:
- Write a clear description that mentions the domain ("product features", "troubleshooting", "pricing").
- Add a Routing Logic rule that names the trigger explicitly:
> "If the user asks about product features, troubleshooting, or how to use a feature, you must use the **product-docs-search** tool before composing a reply. Do not answer from memory."
## Best practices
- **One KB tool per domain.** Separate "Product Docs" from "Internal Policies" from "FAQs" with different tag filters. Cleaner, more predictable.
- **Tune confidence with real queries.** Sit down with a list of 30 representative questions and adjust until precision is high without dropping too many.
- **Always enable conversation history** for chat agents. Voice agents may want to skip it for latency.
- **Don't expose internal-only docs.** A KB tool with no filter sees everything. Be careful what's in your KB.
- **Cite sources when it helps users.** "According to the [Pro Plan docs](#)…" is more trustworthy than an unsourced statement.
- **Use cached answers for stable FAQs only.** Anything that changes (pricing, policies, hours) should go through the LLM path.
## Common pitfalls
| Symptom | Likely cause |
|---|---|
| Agent says "I don't know" too often | Confidence threshold too high, or your KB doesn't actually have content for these questions. |
| Agent hallucinates facts | Confidence too low (low-quality matches still pass), or no KB tool wired so it answers from memory. |
| Wrong-domain results | No filter on the tool. Add tag/source filters to scope it. |
| Follow-up questions fall flat | "Use conversation history" is off. Turn it on. |
| Slow replies | Search size too high, or rich media is rendering large assets. Trim. |
## Legacy reference
The legacy [KB agent config](../../../platform_concepts/AIAgent/kb-agent-config.md) doc describes a related legacy concept (KB *agent*, an entity rather than a tool). Nexus uses the KB *tool* described above - same underlying retrieval, different configuration surface.
---
## Workflow tool
A **workflow tool** is a workflow you've built, attached to an agent so it can call it. Whenever an agent needs to *do* something multi-step - hit an external API, read or write a database, branch on data, run business logic - you build that as a workflow and attach the workflow directly as a tool.
There's **no separate "tool" object to author and no schema to hand-write**: the workflow's **input variables** are the tool's inputs, its **Output node** is what the agent reads back, and its **name** plus the **"When should the AI use this workflow?"** description tell the agent when to call it.
## Two kinds of workflow
When you click **Create** on the Workflows page, you pick one of two kinds. They're built and attached the same way - the difference is what they return:
| Type | Returns | Use it for |
|---|---|---|
| **Workflow** | Data / a result the agent reads | Logic the agent calls as a tool - an API call, a database lookup, a record update, a calculation. |
| **Rich media workflow** | **Rich media** - cards, carousels, quick replies, or [widgets](../../widget-builder/index.md) | A *visual* reply the agent shows in chat - a product carousel, an order-status card, quick-reply chips. |
Most of this page is about the first kind; rich media workflows get their own [section below](#rich-media-workflows) and their own **Rich media workflows** tab on the Workflows page.
## When to use a workflow tool
Use one when:
- The agent needs to hit an external API or database (order lookup, CRM update, catalogue read, payment).
- The action takes multiple steps, or branches on data.
- You want the LLM to *decide when* to act, but the action itself should be deterministic.
- You want to reuse the same logic across several agents.
Reach for something else when:
- You just want to answer from documents - use the [Knowledge Base tool](knowledge-base.md).
- You want to hand off to a human - use [Escalation tools](escalation.md).
- A fixed, multi-step procedure must run the same way every time as part of a longer journey - consider a [guided agent](../guided-agents/index.md).
## Step 1: Build the workflow
In **Studio → Build → Flows**, build the workflow you want the agent to call. A workflow used as a tool typically:
- Receives **input variables** at the start - these are the arguments the agent fills when it calls the tool.
- Does its work (API calls, database reads/writes, conditional branches).
- **Ends with an Output node** that returns a value - Success/Failure plus the data the agent should read.
Any workflow can be attached as a tool - there's no special "agent-callable" flag. But workflows meant for agent use should be small, focused, and have a clear input → output contract.
### Send Message nodes still deliver text bubbles
The "Output node ends the workflow" pattern is canonical, but **Send Message nodes** placed inside a workflow are also delivered to the user. The runtime captures their text bubbles and pushes them through alongside (or instead of) the Output node payload.
- **Use the Output node** for the canonical structured result and anything the agent needs to *read* downstream. (For replies built *from* cards or quick replies, use a [rich media workflow](#rich-media-workflows) instead.)
- **Use Send Message nodes** for one-off text bubbles the workflow wants to render directly - common in "informational" workflows that don't return a value the agent should branch on.
**Gotcha - don't populate rich-media in both.** If your Output node already returns cards or quick replies, do *not* also emit them from a Send Message node - the runtime ignores rich-media in the Send Message stream to avoid double-emit. Text-only Send Message bubbles always deliver.
## Step 2: Name it and say when the AI should use it
Open the workflow's **Edit workflow** dialog and set the two fields that become the tool's contract for the agent:
- **Workflow name** - verb-first and task-shaped: `getOrderStatus`, `getBikeDetails`, `bookAppointment`. The agent references it by this name (e.g. `@getOrderStatus`).
- **When should the AI use this workflow?** - the description the agent reads to decide *whether* to call it. **This is the highest-leverage field on the page.** Say what the workflow returns and exactly when to call it (and when not):
> ✅ "Returns an order's current shipment status by order ID - state (in_transit / delivered), tracking number, and ETA. Use it when the user asks about an order they've already placed; not for new orders or returns."
> ❌ "Order tool." / "Call this when order data is needed."
The studio warns you about this in the field itself: *vague descriptions cause the workflow to be skipped or run at the wrong time.* See [why the description is the most important field](index.md#why-description-is-the-most-important-field).
There's **no separate input/output schema to author.** The workflow's **input variables** are the arguments the agent extracts and fills, and its **Output node** is what the agent reads back. So:
- **Name input variables clearly and describe them.** "The customer's order ID" beats a bare `orderId` - the agent reads the variable to know what to extract.
- **Keep the input list short.** Every input is one more thing the agent has to get right.
- **Return exactly what the agent needs** from the Output node, in a clear shape - nothing more.
## Step 3: Attach it to an agent
On the agent's profile, under **Reasoning & Actions → Tools**, click **+ Add tool** and pick your workflow. That's the whole attach step - the agent can now call it, deciding *when* from the "When should the AI use this workflow?" text you wrote.
Attach the same workflow to as many agents as need it - **tools are shared across the bot.** Attaching a workflow to a specific agent also signals "this belongs to that agent's job," which helps routing send the right topics there.
## Step 4: Test it
Before you rely on the tool:
1. **Run the workflow in the flow editor** with sample inputs and confirm the Output node returns what you expect - wrong field, missing data, or an unexpected shape is much easier to catch here than in a live chat.
2. **Open the agent's [Playground](../../test-debug/index.md)** and confirm the agent calls the workflow at the right moment and reads its result correctly. Use **View trace** on the reply to see the call, the arguments it passed, and the data that came back.
## Step 5 (optional): Make it deterministic with Routing Logic
If this workflow *must* fire for certain user messages (not "the LLM might call it"), add a Routing Logic rule. Example:
> "If the user asks about an order's status, you must call the **getOrderStatus** tool before composing a reply. Do not answer from memory."
See [Routing Logic](../configuration/routing-logic.md).
## Rich media workflows
A **rich media workflow** returns a *visual* reply - cards, carousels, quick replies, or [widgets](../../widget-builder/index.md) - that the agent shows directly in the chat, instead of data the agent reads. Create one with **Create → Rich media workflow** on the Workflows page; they live under the **Rich media workflows** tab.
You build, name, describe (**"When should the AI use this workflow?"**), and attach a rich media workflow exactly like a regular one (Steps 1-3) - the only difference is that it returns rich media. Pick the **card type** that matches your data; the editor's "View format" hint shows the exact JSON shape (both array-of-cards and single-object shapes are supported):
| Card type | What it renders |
|---|---|
| **Default card** | Generic card (title, subtitle, image, buttons). Accepts an array of card objects. The default when you turn on Cards. |
| **Transaction Status** | Single transaction status card (success / failure / pending icon, amount, ref). |
| **Order Tracker** | Multi-step delivery / order timeline. |
| **Contact Card** | Name, phone, email, optional avatar - typically "your account manager is…" patterns. |
| **Payment Receipt** | Itemised receipt with totals and merchant info. |
| **Account Details** | Compact account summary card. |
| **List** | A vertical list of items with title / subtitle / optional action - different shape from a carousel of Default cards. |
| **Slider** | Range / value slider card for numeric input. |
| **Product Card** | E-commerce product (image, name, price, CTA). |
| **Payment List With Button** / **Without Button** | Itemised payment list with or without the pay-CTA at the bottom. |
| **Transaction List With Multi Select** / **Single Select** | A list of transactions the user can pick from. |
Pick **Default card** for a standard carousel; pick a specialised type when its native shape matches your data and you want type-specific styling and validation. Leaving the card type unset is equivalent to **Default card**.
**How the agent uses it:**
- **It's a tool call, not a description.** Reference it in instructions by name, *as a call* - *"Call `@display_cart` to show the cart"*, not *"display the cart"* - otherwise the model narrates the intent instead of rendering the media. See [Referencing tools in prompts](index.md#referencing-tools-in-prompts).
- **For custom interactive UI** beyond the built-in card types (forms, multi-step pickers, calculators), build a [widget](../../widget-builder/index.md) and return it from a rich media workflow.
## Best practices
- **One workflow, one tool.** Don't build a single mega-workflow that branches on a "mode" argument - the LLM will pick the wrong mode. Build separate, focused workflows.
- **Keep workflows fast.** A tool call adds latency to the conversation. Aim for under ~2 seconds end-to-end; cache where you can.
- **Always handle the Failure path.** Make sure the workflow has a Failure output and that its payload tells the agent what went wrong, so the agent can recover or apologise gracefully instead of stalling.
- **Write "When should the AI use this workflow?" for the model, not for yourself.** Answer "what does it return, and when should you call it?" in plain language. Someone will tweak this bot in six months - make it self-explanatory.
- **Name input variables clearly.** They *are* the tool's input contract; clear names and descriptions are what let the agent fill them correctly.
## Common pitfalls
| Symptom | Likely cause |
|---|---|
| Agent calls the workflow with missing/empty inputs | Input variables aren't clearly named or described, or the "When should the AI use this workflow?" text doesn't make the required inputs obvious. |
| Agent never calls the workflow | The description doesn't match how users actually phrase things. Reword it, or add a Routing Logic rule. |
| Workflow fires but the agent ignores the result | The Output node doesn't return the data the agent needs, or returns it in a confusing shape. |
| Workflow fires twice in one turn | Two workflows' descriptions overlap. Sharpen each so its trigger is distinct. |
## Legacy reference
The legacy [Call workflow](../../../platform_concepts/AIAgent/call-workflow.md) doc covers similar ground for legacy-platform bots. On Nexus you attach a workflow directly as a tool as shown above; the underlying concept (a workflow the agent can call) is unchanged.
---
## Deploy chatbot using the GTM integration
This document provides instructions for deploying a web bot on your website, if it is integrated with Google Tag Manager (GTM).
## Setup chatbot on the website using GTM integration
To set up a chatbot using GTM integration, follow the steps outlined below:
### Create a Tag
1. Login to your [Google Tag Messenger](https://tagmanager.google.com/) and create an account.
2. Navigate to [Google Tag Messenger](https://tagmanager.google.com/) account and select the container you want to configure.
3. Click **Tags** > **New**.
4. Choose the **Custom HTML** tag type.
5. Copy the below script and paste it under the **Custom HTML** tag.
```js
```
:::note
In the above script, you need to update the "Bot ID" and appended regions - r0/r1/r2/r3/r4/r5.
:::
| Region Code | Region | Host |
| --- | --- | --- |
| R0 | INDIA - India | `https://cloud.yellow.ai` |
| R1 | MEA - UAE North | `https://r1.cloud.yellow.ai`|
| R2 | JAKARTA | `https://r2.cloud.yellow.ai` |
| R3 | SINGAPORE | `https://r3.cloud.yellow.ai` |
| R4 | USA | `https://r4.cloud.yellow.ai` |
| R5 | EUROPE | `https://r5.cloud.yellow.ai` |
6. Click **Save** to change the configuration changes.
### Create a Trigger
To control when the chatbot loads on your website, you need to define when to load the bot on your website with a trigger.
To create a Trigger, follow these steps:
1. Click **Trigger** > **New**.
2. Choose the trigger type as **Page view**.
3. In the Page view section, select **Some page views**.
4. In the *Trigger configuration*, under "Page view," perform the following:
i. In *This trigger fires on*, select **Some Page Views**.
ii. In *Fire this event when an event occurs and all of these conditions are true* section, select **Page URL** and **Contains** from the drop-down and enter the URL of your website page.
* Click **Save**.
A reference to your trigger associated with the tag will be displayed.
5. On top of the menu bar, click **Preview**.
6. Enter your website URL and click **Connect**.
7. Enter the URL of your site to connect your chatbot, and click **Connect**.
This will redirect to your website, and the Tag Assistant will be connected. Open the chatbot to start the conversation.
---
## IVR for cloud
:::note
All the Voice agents created after July 2022 operate on the cloud. Refer to [this](https://docs.yellow.ai/docs/platform_concepts/channelConfiguration/ivr-bots) article for the latest update.
:::
Interactive Voice Response (IVR) channel can be deployed and hosted in a cloud environment. Configuring IVR voice agents on the cloud allows businesses to deliver an efficient and personalised customer experience.
While building voice agents, you need to link the voice agent to a phone number so that when users call this number, they can have a conversation with the voice agent.
Once you have built the personalized voice agent, you need to connect your voice agent with a number to enable interactive voice responses. This IVR number is also termed as DID (direct inward dailing) number.
:::note
- The associated number will be used for making (an outbound) call or receiving (an inbound) call.
- This is a paid feature. You need to upgrade to enterprise subscription to access this feature. To enable this feature for your voice agent, contact [support](mailto:support@yellow.ai).
- Phone numbers are a limited resource and are leased from downstream providers at a monthly cost. Ensure that only the required phone numbers are being added to the voice agent.
:::
## Add IVR number
To add a IVR number, follow these steps:
1. Log in to https://cloud.yellow.ai and navigate to **Overview > Channels > Voice > IVR** channel.
2. Verify the voice agent is selected in the required environment on the channels page to which you want to associate a number. Click **+Add IVR Number**.
3. Select the voice agent **Region** and assign one or more **IVR number** based on your use case. There could be different types of numbers, like landline or mobile, available for association. Select the number(s) as per the requirements. Click **Add**.
4. Click **Yes, proceed**.
:::note
Currently, only Karnataka (India) Phone numbers are available, other countries will be added soon.
:::
5. The IVR numbers will be successfully added.
## Delete IVR number
To delete an IVR number, follow these steps:
1. Click the delete icon next to the number that you want to delete.
2. A pop-up is displayed with a confirmation message **Do you really want to delete? This process cannot be undone**, click **Delete**.
:::note
* Reclaiming a deleted number is a highly challenging and manual process. Ensure the details before removing a phone number from your Bot.
:::
3. The IVR number will be successfully deleted.
---
## SMS
:::note
* If businesses wish to set up the SMS channel in a specific country, you need to contact the Yellow [support](mailto:support@yellow.ai) team for assistance and guidance. However, if they prefer to set up SMS channel for USA, you need to utilize the [Twilio SMS channel](https://docs.yellow.ai/docs/platform_concepts/channelConfiguration/twilio-sms) for seamless integration and management.
* For pricing details, contact [procurement](mailto:procurement@yellow.ai).
:::
SMS (Short Message Service) is a messaging channel that allows you to send image and text messages to users through their registered phone numbers.
Connecting the SMS channel to the Yellow.ai Cloud platform enables the following:
* **One-way conversations**: Send campaigns
* **Two-way conversations**: Automated responses and live agent support
1. **[Send campaigns](https://docs.yellow.ai/docs/platform_concepts/engagement/outbound/outbound-campaigns/run-campaign#31-sms-campaign)**: Through SMS, you can send campaigns to inform users about discounts, sales, or special offers.
* **One-way conversation**: Supports one-way communication where only the sender shares information and recipients cannot respond. These messages include promotional offers, transactional updates, alerts, or notifications.
2. **Automated replies and live agent support**: Enables automatic responses to user messages received via SMS and provides immediate assistance with live agents.
* **Two-way conversation**: Supports two-way communication, allowing both sender and recipient to exchange conversations. These messages can include messages such as live agent support, automated replies, order tracking, or feedback.
3. **Supported message types**: You can use Text message type to send the SMS.
:::note
To send SMS using one-way or two-way communication depends on the regulations, guidelines, or requirements set by each country.
:::
#### Limitations of SMS channel
| Option | Character limit |
--------|------------------|
Text message | 160 characters
## Segment in SMS channel
A segment is a part of a text message limited to a specific number of characters, typically 160 characters in standard 7-bit encoding. In the context of SMS messaging, particularly in the GSM (Global System for Mobile Communications) standard, an SMS segment consists of up to 160 characters when using standard 7-bit encoding.
**Key points about SMS Segments:**
* **Character limit:** Each segment can contain up to 160 characters (7-bit encoding) or 70 characters (Unicode).
* **Concatenated SMS:** When a message exceeds the character limit of a single segment, it is split into multiple segments. These segments are sent individually and then reassembled by the recipient’s device to display as a single message. Some operators may send it as a single message without splitting.
- Each concatenated segment usually contains a few characters less than the maximum (for example, 153 characters for 7-bit encoding) to include information for reassembly.
* **Cost implications:** Each segment counts as a separate SMS for billing, so longer messages are more expensive.
**Example of SMS segmentation**
* **Single segment message:**
- **Message**: "Hello, this is a test message to explain SMS segmentation".
- **Character count**: 59 characters.
- **Segments used**: 1 (fits within the 160-character limit).
* **Multi-segment message:**
- **Message**: "Hello, this is a test message to explain SMS segmentation. Each part of the message must fit within the character limit. If the message exceeds the limit, it will be split into multiple segments."
- **Character count**: 197 characters.
- **Segments used**: 2
* **Segment 1**: "Hello, this is a test message to explain SMS segmentation. Each part of the message must fit within the character limit. If the message exceeds the limit, it will be split i" (153 characters)
* **Segment 2**: "nto multiple segments." (44 characters)
You can configure SMS services for the following countries:
* [Configure SMS service for Indian numbers](https://docs.yellow.ai/docs/platform_concepts/channelConfiguration/sms-outbound-india)
---
## Create WhatsApp bot
This document provides details on the best practises and limitations that you need to follow while creating the WhatsApp (WA) bot. For more information on WA limitations, click [here](https://docs.yellow.ai/docs/platform_concepts/channelConfiguration/whatsapp-channel#limitations-of-whatsapp-channel).
## Create a flow for WhatsApp bot
Before creating a flow for the WhatsApp bot, you need to consider the following points:
* Determine the purpose and scope of the bot (use case) to create a flow for a WhatsApp bot, like what type of questions or requests the bot should handle based on your use case.
* Select the appropriate environment for flow creation. The following are the bot environments:
* Two environments - Develpoment and Live
* Three environments - Sandbox, Staging, and Production
* If a flow is configured and published in a specific environment, it will not respond to queries in other environments.
* If your bot has 3 environments such as sandbox, staging, and production, you need to use sandbox bot for building the chatbot or making changes in existing flows. Once you are done with creating the flows, you can publish the bot from the sandbox to staging.
* Include intents for common questions or requests that align with your conversation flow, aiding in proper training of the bot to identify user intent.
* Use WhatsApp nodes such as [WhatsApp quick replies](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-node-overview/quick-replies), [WhatsApp list](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-node-overview/whatsapp-list-node), and [prompt carousel](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-node-overview/carousrel-node) to enhance the flow's functionality.
### Using WhatsApp nodes
#### **Prompt carousel node**
The WA bot will respond with a number list even if the buttons are configured in the quick reply node. In this case, you can use the [prompt carousel](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-node-overview/carousrel-node) node instead of quick reply to display the buttons in the bot response.
##### **Limitations of prompt carousel**
* Supports a single carousel card.
* Supports a maximum of 3 buttons.
* The maximum number of characters supported is 1024.
* Carousel button - The maximum number of characters supported is 20.
#### **Quick reply node**
##### **Best Practices**
* To know more about how to use the WA quick reply node, click [here](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-node-overview/quick-replies).
* You can trigger a flow when a user clicks on the quick reply option on WhatsApp. For more information, click [here](https://docs.yellow.ai/docs/cookbooks/studio/qr-node).
* To add a quick reply button, you need to switch the channel filter to Website. Eventually, if you try to add a button in the WA channel filter, then the add button option will be disabled.
* If you want to delete a quick reply node, you have to switch to Website from the channels filter and then delete the buttons.
:::note
Using Quick Replies, you cannot add a message with a CTA in WA. It is recommended to use a WhatsApp template and pass the link as a CTA.
:::
##### **Configure Dynamic WA quick reply and Dynamic WA list message**
* For more information on how to create dynamic quick replies, click [here](https://docs.yellow.ai/docs/cookbooks/studio/dynamic-quickreplies).
##### **Pass data to quick reply buttons and title using variable**
* You can also pass the data to the quick reply buttons and title using the variable. Use the following code to pass the data:
`{{{variables.info}}}, {{{variables.info1}}}`
For more information on how to create a variable, to store, and retrieve data from variables, click [here](https://docs.yellow.ai/docs/platform_concepts/studio/build/bot-variables#31-create-a-variable-via-nodes).
##### **Limitations of Quick reply**
* The WhatsApp quick reply supports a maximum of 3 buttons and 20 characters per button. If more than 3 buttons are added, it defaults to a numbered list.
* If a quick reply button exceeds 20 characters, the message containing that button will not display while the bot is reacting.
#### **WhatsApp list**
* To know more about how to use the WA list node, click [here](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/prompt-node-overview/quick-replies).
#### **WA list options**
#### **Limitations**
* A maximum of 10 buttons can be added. Multiple buttons cannot be selected at once and are not supported in notifications.
* The character limit for the body is 1024.
* The character limit for the footer is 60.
* The character limit for button text and response is 24.
#### **Limitations of supported media types**
| Options | Limit |
|---------------------|-----------------|
| Image type | Supported image types are JPG and PNG.
| Image size | Supported image size is 5MB.
| Image diemensions | Supported image dimension is 250*250.
| Video type | Supported video type is MP4.
| Video size | Supported video size is 15MB.
| Video dimensions | No restrictions.
| File size | Supports any valid MIME type up to 15 MB in size.
### WhatsApp template
A WhatsApp template is a predefined message format that is used to send outbound messages to your users on the WhatsApp messaging platform. It is designed to enable businesses to send structured and consistent messages to your users. For more information on the template and guidelines, click [here](https://docs.yellow.ai/docs/platform_concepts/engagement/outbound/templates/whatsapptemplate).
After creating the template, it must be submitted for Facebook review. Usually, the review process takes up to 48 hours. The template will be accepted if it meets Facebook's rules.
:::note
To view the status of the template approval, you need to click on the **Sync template** button.
:::
For more information on how to execute a campaign, click [here](https://docs.yellow.ai/docs/platform_concepts/engagement/outbound/outbound-campaigns/run-campaign#33-whatsapp-campaign).
For more information on how to trigger a flow when a user clicks on a quick reply option on WhatsApp, click [here](https://docs.yellow.ai/docs/cookbooks/studio/qr-node).
### Quality rating of a WA template
When you are executing a WhatsApp campaign, you need to use a template, and if users block or report the number or template, then the quality rating of the template or the number will reduce. If the quality rating of the number is marked as flagged for more than 7 consecutive days, the messaging limit will be reduced to the immediate lower tier. For example, 100000 to 10000 or 10000 to 1000.
To ensure that the quality rating does not become low, click [here](https://developers.facebook.com/docs/whatsapp/messaging-limits/).
To view the quality rating of the template and phone numbers, follow these steps:
1. Login to your Facebook business manager account and select **Account tools > Message templates**.
2. To view the quality rating of phone numbers, click **Account tools > Phone numbers**.
## Set up a WhatsApp channel
To set up a WhatsApp channel, you need to have an active WhatsApp business account. For more information, click [here](https://docs.yellow.ai/docs/platform_concepts/channelConfiguration/whatsapp-configuration).
### Apply for official business account
Once your account is set up, you need to apply WA for an official business account.
To apply for an official business account, follow these steps:
1. Login to your Facebook business manager account and select **Accounts > WhatsApp accounts**.
2. Under *Account* tools, select **Phone Number** and click on the **Setting** icon.
3. Under *Phone numbers*, select **Profile** > click **Submit Request** to apply for the official business account.
Once you apply for an official business account, you need to verify your business account with Facebook. For more information, click [here](https://docs.yellow.ai/docs/platform_concepts/channelConfiguration/whatsapp-configuration#12-verify-business-account-with-facebook).
### Change WA display picture and description
After setting up your WA channel, you can change the display picture and description.
To change the display picture and description, follow these steps:
1. On the WA channel page, click on the icon highlighted below and click **Edit**.
2. Under **Basic details**, you can edit the display picture and description based on your requirements.
:::note
* You cannot change the display name on the platform. To change the display name, you have to go to the Facebook business manager account.
:::
### Change WA display name
If your WhatsApp Official Business Account (OBA) or non-OBA display name encounters initial rejection during the embedded sign-up process or needs to be changed in the future, you need to reapply from your own FBM.
You need to follow the [WhatsApp business account guidelines](https://docs.yellow.ai/docs/platform_concepts/channelConfiguration/whatsapp-business-account-guidelines) before applying or changing the display name for your business.
To change the WhatsApp OBA (with a green tick mark) or non-OBA display name, follow these steps:
1. Login to your Facebook business manager account and navigate to **Accounts > WhatsApp accounts** > **WhatsApp Manager**.
2. Select **Phone numbers**.
3. To check the approval status of your display name, click **View** corresponding to the display name.
3. For non-OBA, under *Name*, click **Edit** icon to change the display name.
4. Enter the **New display name** and click **Next**.
5. To confirm the approval status of your display name, click **View** corresponding to the display name.
6. For OBA, navigate to [Facebook's direct support](https://business.facebook.com/direct-support/?business_id=1333020976800454) and raise a ticket to update the OBA display name.
* To verify the approval status of your display name, click **View** corresponding to the display name or check your ticket.
Once the display name is approved, share the WABA ID, phone number, and new display name details with our [support](mailto:support@yellow.ai) team so that they can update it in the back-end.
### Apply for your WhatsApp Official Business Account
To apply for an Official Business Account (OBA) and secure a green tick mark for your business on WhatsApp, follow these steps:
1. Login to your Facebook business manager account and navigate to **Accounts > WhatsApp accounts** > **WhatsApp Manager**.
2. Select **Phone numbers**.
3. Click **Settings**.
4. Click **Profile** > under *Official business account* > **Submit request**.
5. Enter the following details in the respective field:
* **Country of operation**: Enter the name of your parent business or brand.
* **Supporting links**: You have the option to submit up to 5 supporting links, particularly from well-known publications such as India Today, Economic Times, Wall Street Journal, Reuters, Wikipedia, and Business Insider.
* Click **Submit**.
Once your account is reviewed, you will be notified about the status of your OBA. If your account is rejected, you can submit a new request after 30 days.
## Test your WhatsApp bot
After successfully creating your WhatsApp business account and configuring the flow, you need to select the **WhatsApp** channel from the **Channels** filter to test your bot and ensure all the flows you configured are working as intended. For more information, click [here](https://docs.yellow.ai/docs/platform_concepts/channelConfiguration/whatsapp-configuration#test-your-bot-on-whatsapp).
### Add WhatsApp number for testing
You can add the WhatsApp number for testing purposes in the Live environment.
:::note
You can test the WA bot in staging and sandbox environments by enabling **Development mode**. The numbers that you have added for testing purposes will respond with the Staging/Sandbox configured flows.
:::
1. On the **Channels** page, select WhatsApp messenger in the Live environment, click on the **More options** icon, and select **Edit** icon.
3. **Enable development mode** using the toggle button.
4. Enter the number in **Developer WhatsApp number**.
5. To add more WhatsApp business numbers, click **Add phone numbers**.
6. Click **Save**.
### 24-hour WhatsApp policy
If a live agent connects with the WhatsApp bot user and does not close the ticket within 24 hours of the last message sent by the user, the chat will be automatically disabled under the **Chats** section > **Bot messages** of the Inbox module. For more information, click [here](https://docs.yellow.ai/docs/platform_concepts/inbox/chats/reinitiatewachats#expchats).
To upgrade your WhatsApp tier and messaging limit, click [here](https://developers.facebook.com/docs/whatsapp/api/rate-limits#quality-rating-and-messaging-limits).
---
## Common errors while sending WhatsApp messages
When sending messages via WhatsApp, you may encounter errors that prevent successful delivery. This guide outlines common error messages, their descriptions, and possible resolutions.
## WhatsApp error codes and resolutions
| **Error Code** | **Error Message** | **Description** | **Resolution** |
|--------------|----------------|---------------|--------------|
| **4** | Sending failed because you sent too many messages too quickly. | You reached your API call rate limit. | Try again later. If the issue persists, contact the [Meta Help Center](https://www.facebook.com/business/help). |
| **80007** | Sending failed because you reached your rate limit. | You reached your WhatsApp messaging rate limit for your plan. | Try again later or upgrade to a plan with a higher limit. |
| **130429** | Sending failed because you reached the maximum number of messages allowed within a period. | Cloud API message throughput has been reached. | Reduce message frequency or upgrade to a plan with higher limits. |
| **131048** | Sending failed because too many previous messages were blocked or flagged as spam. | Restrictions have been applied due to multiple blocked or flagged messages. | Reduce message frequency to avoid spam flagging. |
| **131056** | Sending failed because you sent too many messages to the same recipient too quickly. | Too many messages were sent to the same recipient in a short time. | Wait before retrying. You can message a different recipient immediately. |
| **368** | Sending failed because your account may be blocked temporarily for policy violations. | Your WhatsApp Business Account has been restricted due to a policy violation. | Review [Meta's Policy Enforcement](https://www.facebook.com/business/help) and contact Meta if needed. |
| **131031** | Sending failed because your account may be locked temporarily. | Your WhatsApp Business Account has been restricted due to policy violations or unverifiable data. | Verify your account and ensure compliance with Meta's policies. Contact Meta if needed. |
| **2** | Sending failed due to an unavailable service. | Temporary server downtime or high traffic. | Try again later. |
| **131000** | Sending failed due to a technical glitch. | An unknown error occurred. | Try again later. If the issue persists, contact Meta. |
| **131016** | Sending failed due to a technical glitch. | Internal server error while sending the message. | Try again later. If the issue persists, contact Meta. |
| **131021** | Sending failed because the sender's and recipient's phone numbers are identical. | The sender phone number is the same as the recipient's. | Use a different recipient number. |
| **131026** | Sending failed due to issues with the recipient’s phone number or WhatsApp account. | The recipient’s number is invalid, they use an outdated WhatsApp version, or they have not accepted WhatsApp's latest Terms of Service. | Ask the recipient to: 1. Confirm they can send a message to your WhatsApp business number. 2. Accept WhatsApp’s latest Terms of Service. 3. Update to the latest WhatsApp version. 4. Wait and try again if due to frequency capping. |
| **131042** | Sending failed due to issues with your WhatsApp account settings or payment method. | Possible causes: unattached payment account, exceeded credit limit, inactive payment account, timezone or currency issues, or exceeding free-tier conversations without a valid payment method. | Review your account settings and payment method. Contact Meta if needed. |
| **131047** | Sending failed because the recipient has not responded in a while. | More than 24 hours have passed since the recipient last replied to your sender number. | Restart the conversation by sending a new message template. |
| **131052** | Sending failed due to an unsupported media type. | The media type is not supported. | Ensure you are using a supported media type. Contact Meta for supported formats. |
| **132001** | Sending failed because the template is not approved by Meta in this language. | The template does not exist in the specified language or is not approved. | Use an approved template. |
| **132007** | Sending failed because the template content violates a WhatsApp policy. | The template violates a policy (e.g., incorrect format, character limitations). | Modify the template to comply with Meta’s policies. Contact Meta if needed. |
| **132015** | Sending failed because Meta has paused this template. | Templates with a low-quality rating have been paused. | Edit and improve the template quality before resending. |
| **133004** | Sending failed due to an unavailable service. | A technical issue occurred. | Try again later. If the issue persists, contact Meta. |
---
## Checking message errors on the portal
1. You can view these errors in the **Data/Messages API** on yellow.ai portal.
2. Use the following API to retrieve message details for a specific phone number. This API call fetches message logs related to the given phone number.
- Search for the failed message in the response.
- Check the **error message description** to understand the issue and find the resolution.
```
https://app.yellow.ai/api/agents/data/messages?bot={{{botid}}}&uid={{{phonenumber}}}&limit=100
```
:::info
If the issue persists, refer to the resolution steps above or contact the [Meta Help Center](https://www.facebook.com/business/help) for further assistance.
:::
---
## WhatsApp messaging limits and quality rating
This guide helps you understand WhatsApp’s messaging limits, current limits and ratings, and how to increase your messaging level.
## Messaging limits
WhatsApp imposes limits on the number of messages a business can send to users, and this is categorized into different tiers based on the volume of messages sent. To learn more about messaging limits, click [here](https://developers.facebook.com/docs/whatsapp/messaging-limits).
There are four levels of messaging limits in a rolling 24-hour period:
* Tier 1: 1,000 unique customers per day
* Tier 2: 10,000 unique customers per day
* Tier 3: 100,000 unique customers per day
* Tier 4: Unlimited messages
:::note
* All the above messaging limits are business initiated messages.
* Every business account starts at tier 1 after registering a phone number.
* It takes at least 7 days to reach unlimited messaging.
:::
## How to increase the messaging limits
The messaging limits on WhatsApp are designed to automatically adjust based on the quality and volume of messages sent to users. To increase messaging limits on your number, consider the following conditions:
* **Phone number quality**: Ensure that the quality of your phone number is not low, as this can impact your eligibility for a limit increase.
* **Messaging volume**: Over a 7-day period, the number of messages sent should be at least twice the number of unique customers supported in the current messaging limit.
* **Threshold**: The phone number must consistently operate within the current messaging limit for at least 48 hours. Once the business reaches this threshold, its limits are automatically increased.
Let's consider an example to illustrate the tiered structure of WhatsApp messaging limits:
Assume that you're using a marketing platform with tiered plans based on the number of users you can reach. Currently, you are in Tier 1, where the limit is 1,000 unique users per 24 hours.
Over the course of a 7-day period, if you consistently engaged with more than 2,000 users and maintain a positive engagement rate, WhatsApp will automatically upgrade you to tier 2. In Tier 2, your limit increases to 10,000 users per 24-hour period.
Once your account reaches the threshold, the system automatically promotes you to the next tier. The transition period takes at least 48 hours, during which you must send your weekly limit or daily limit of messages for minimum two days.
## Quality rating
Quality rating on WhatsApp is an evaluation of how messages have been received by recipients over the past seven days. It is determined by analyzing a combination of quality signals, which include user feedback signals like recent blocks, the reasons users provide when they block a business, and other reporting issues.
:::note
* If your quality rating reaches low, your account status will change to flagged or restricted, and you will receive an email notification in Business Manager as a warning.
:::
### Quality rating status
There are 3 different quality ratings:
* High quality: Green
* Medium quality: Yellow
* Low quality: Red
### Phone number status
When the quality rating decreases, the phone number status undergoes the following changes:
* **Connected**: Indicates that your phone number is operating correctly and is successfully linked to your account, establishing a connection with the WhatsApp Business API environment.
* **Flagged**: Indicates when the quality rating reaches a low state. If the phone number is marked as flagged for more than 7 consecutive days, the messaging limit will be reduced to the immediate lower tier.
* **Restricted**: Indicates that the number has reached the [messaging limit](#messaging-limits). During a restricted phase, you cannot send any notification messages until the 24-hour window is reset.
* **Pending**: Indicates that your account is awaiting verification, the certificate is currently unavailable, or the phone number is currently linked to another WhatsApp account.
* **Offline**: Indicates that your business name has been confirmed, a certificate is available to connect to the WhatsApp Business API, but there is currently no active connection.
In the *Status* column, you can verify the current status of your sender phone number.
### How to check quality rating
You can check your phone number status, quality score, and sending limits for your WhatsApp Business account in your Facebook Business account.
#### To check quality rating, follow these steps:
1. Login to your Facebook business manager account and navigate to **Accounts > WhatsApp accounts** > **WhatsApp Manager**.
2. Select **Phone numbers**.
3. In the Quality rating column, you can view the rating.
### How to improve quality rating
If your quality rating is low, WhatsApp will automatically reduce your business initiate conversation limit and also you cannot change or request for change to your quality rating. It is recommended to follow WhatsApp's guidelines to maintain high quality.
To improve quality rating on WhatsApp, consider the following points:
* **Adhere to WhatsApp Business Policy**: Ensure that your message templates comply with WhatsApp's business policy.
* **Opt-in messages only**: Send messages only to users who have explicitly opted in to receive communications from your business. Avoid messaging users who have not provided consent.
* **Clarity and personalization**: Make sure your messages are clear, personalized, and useful to users. Avoid sending open-ended welcome or introductory messages.
* **Messaging frequency**: Be cautious about the frequency of your messages. Avoid sending users too many templates a day.
* **Review recent templates**: Check for new templates sent within the last 7 days. This practice can help to identify and rectify any issues with specific templates that might be affecting your quality rating.
---
## WhatsApp pricing policy
# WhatsApp Pricing Model (June 2025 Update)
Meta has introduced a **new per-message pricing model** for WhatsApp Business Platform and APIs.
This marks a significant shift from the previous **per-conversation** billing model.
## Key Changes (Effective July 1, 2025)
* **Billing & Pricing**
* Conversations → **Messages**
* Business-initiated → **Paid messages**
* User-initiated → **Free messages**
* Referral-initiated → **Deprecated**
[Learn more about WhatsApp pricing policy](https://developers.facebook.com/docs/whatsapp/updates-to-pricing/).
* **Analytics & Reporting**
* `conversation_analytics` field **deprecated in Graph API v25.0 (late 2025)**
* All new metrics will be **message-based**
* Historical conversation data must be **exported before cutoff**
* **Template Management**
* Utility templates must meet a **stricter, non-promotional definition**
* Expect possible **re-categorization notices** from WhatsApp
---
## Changes required from Service Provider
### 1. Billing and Cost Management
* Update all **pricing calculations** from conversation-based to per-message billing.
* Review and update **contracts and SLAs** to reflect per-message pricing.
* Adapt billing systems to account for **free service/utility messages**.
### 2. Template Management
* Audit and **re-categorize templates**.
* Ensure **utility templates** remain non-promotional and user-specific.
* Prepare for re-categorization enforcement by WhatsApp.
### 3. Reporting & Analytics
* Shift dashboards from **conversation-based IDs** → **message-based IDs**.
* Educate **finance and analytics teams** about the new KPIs.
* Maintain **parallel logic** for transition until old data is phased out.
## Pricing Model Comparison
| **Feature/Aspect** | **Before July 1, 2025** | **After July 1, 2025** |
| ----------------------------------- | ------------------------------------ | ------------------------------------------- |
| **Pricing Model** | Per-conversation (24h session) | Per-message |
| **Utility Template Messages (CSW)** | Charged if outside free tier | Free if sent within customer service window |
| **Service Conversations** | Free up to 1,000/month, then charged | Unlimited free |
| **Volume Tiers** | Not available | Available for utility & authentication |
| **Template Category Definition** | Broader definition | Stricter (non-promotional, user-specific) |
| **Webhook/Analytics Fields** | Conversation-based IDs (`CBP`) | Message-based IDs (`PMP`) |
| **Authentication Rates** | Per conversation, limited markets | Per message, expanded to more markets |
| **Marketing Messages Lite API** | Conversation-based rates | Cloud API marketing rates apply |
📌 **Glossary**
* **CBP** = Conversation-Based Pricing
* **PMP** = Per-Message Pricing
* **CSW** = Customer Service Window
---
## Transition Guidance
* Export all **conversation analytics data** you may need before **Graph API v25.0** is released.
* Expect **non-comparability** between pre-July 1 (CBP) and post-July 1 (PMP) data.
* During migration, maintain **dual tracking** of CBP and PMP to ensure continuity in dashboards and billing reports.
## Benefits of Per-Message Pricing
* **Simpler billing** – charges directly tied to message volume.
* **Unlimited free service messaging** within CSW.
* **Expanded global coverage** for authentication messages.
* **Volume discounts** available for high-utility use cases.
## Action Checklist ✅
* [ ] Update billing logic to per-message model.
* [ ] Export historical conversation analytics.
* [ ] Re-categorize existing templates.
* [ ] Update reporting dashboards and train teams.
* [ ] Review customer contracts for new billing rules.
:::note
⚠️ **Important:** After **July 1, 2025**, WhatsApp **will no longer support conversation-based pricing, analytics, or referral categories**.
:::
### Old vs. New WhatsApp Pricing Model
| Scenario | Old Model (Conversation-based) | New Model (Per-message) |
| ------------------------------------------------------------------ | ------------------------------------------------- | --------------------------------------- |
| **Two messages, same category** (e.g., 2 utility) | 1 Utility conversation | 2 Utility messages |
| **Two messages, different categories** (e.g., marketing + utility) | 1 Marketing conversation + 1 Utility conversation | 1 Marketing message + 1 Utility message |
| **Single mixed message** (utility + marketing content) | 1 Marketing conversation | 1 Marketing message |
---
### What this means for businesses
* **More transparency:** Costs now scale directly with the volume and type of messages sent.
* **Granular control:** Marketing and utility spends can be tracked and optimized separately.
* **Budget predictability:** Teams can forecast spend with higher accuracy, especially for large-scale campaigns.
* **Operational shift:** Businesses may need to rethink engagement strategies to avoid unnecessary message sends that could increase costs.
---
## Apple Business Chat
Apple Business Chat (ABC) is a messaging app (iOS) that allows you to chat with your businesses through the Messages app on their Apple devices. You can send text, images, videos, files, and attachments with text captions for the businesses to address user queries related to the brand. The platform supports 2-way communication for ABC channel.
Apple Business Chat integration helps businesses to provide customer support, promote their brand, and schedule appointments.
For instance, if you have a question about a product, you can use the AI-agent integrated with the ABC channel to receive instant assistance without having to connect with an agent.
In this article, you will learn:
* [How to setup messages for Business account](#setup-your-abc-channel)
* [How to connect messages for business with Yellow.ai](#connect-abc-channel-to-your-bot)
* [How to test your AI-agent on ABC](#test-your-bot-on-abc)
## Setup your ABC channel
You can create a message for business account by using the [Apple business register](https://register.apple.com/business/ui/services/welcome) website.
#### Prerequisite
* You need to [create an Apple ID](https://appleid.apple.com/account).
### Step 1: Setup messages for Business account
To setup messages for Business account, follow these steps:
1. Go to [Apple business register](https://register.apple.com/business/ui/services/welcome) and click **Sign In**.
2. Enter your Apple ID to continue.
3. Enable the checkbox to agree to the terms and conditions, and click **Agree** to create your business chat account.
### Step 2: Create a message for business account
To create messages for business account, follow these steps:
1. Click on **Get started** to create a Business account.
2. Perform the following actions to add Messages for Business Account and Messaging for Business Service Providers for your organization:
i. In **Messages**, click **+ Add** corresponding to **Messages for business accounts** and **Messaging service providers**.
ii. In **Settings**, click **+ Add** corresponding to **Private Access Tokens Issuers**.
iii. In **Apple Business Register**, click **+ Add** corresponding to **Brands** and **Members**.
iv. Click **Done**.
3. Choose **Messages for Business Accounts**.
4. Select the checkbox to **Agree terms and conditions** of Apple and click **Agree** to create **Messages for Business Accounts**.
5. Click **+ Add New** to create a Business Chat account for your brand. For more information, see [Create a commercial business chat account](https://register.apple.com/resources/messages/messaging-documentation/register-your-acct#create-a-commercial-business-chat-account).
### Step 3: Register your messages for business service
1. Click **Get Started** to register your Messages for business service.
2. Enable the checkboxes to agree on the design guidelines, business policies, and best practises, then click **Next**.
3. Enter the following details about your organization and click **Next**.
* **Legal Name of Organization**: Enter the display name of your brand.
* **Website**: Enter the web URL of your brand.
* **Head Office Address**: Enter the head office's address of your organisation.
### Step 4: Commercial account
A commercial account is used to directly interact with your customers.
To create a commercial account, follow these steps:
1. Select the business chat account type as **Commercial account** and click **Next**.
2. Enter the technical contact user name and sponsoring executive (this field is optional) for your account and click **Next**.
3. Select the number of public locations for your business. If your business has only one location accessible to the public, than select One Public Location and enter your location information.
4. Click **Next** to proceed.
### Step 5: Provide your brand information card details
You need to create a brand if your business has multiple locations or an online business.
1. You can either add a new brand or select an existing one. For new brands, you need to enter the brand details and click **Add**.
2. Select your time zone and estimated timeline for a live agent to respond to your customers during office hours, and click **Next**.
### Step 6: Add your brand identity details
To add your brand identity details, follow these steps:
1. Upload a square logo, you will see it in the conversation list. Click **Next**.
:::note
The square logo should have a full color background, and it cannot be personal or product pictures.
:::
2. Verify your logo’s appearance in both dark and light mode previews. Select the checkboxes and click **Next**.
3. Add a wide logo, which will be shown at the top of the conversation. Click **Next**.
:::note
The wide logo should have a transparent background and text.
:::
4. Verify the appearance of the logo in both dark and light mode previews and click **Next**.
5. Verify the color and logo in both dark and light mode previews. Select the checkboxes and click **Next**.
### Step 7: Confiure Messaging service provider
1. Select your Messaging Service Provider (MSP) as **Yellow.ai** or provide your MSP's URL. Click **Next** to continue.
### Step 8: Ready to launch
After configuring your Message Business account, you need to contact the [support](mailto:support@yellow.ai) team to get your account reviewed by Apple.
1. Configure your iOS entry points. Once your business chat buttons are publicly available, go to the [Apple Business Register](https://register.apple.com/business/ui/services/welcome) to enable your business. For more information, click [here](https://register.apple.com/resources/messages/messaging-documentation/customer-journey#entry-points).
2. Configure the business chat button on your website and app. For more information, click [here](https://register.apple.com/resources/messages/messaging-documentation/chat-with-customers#adding-a-messages-button-to-your-website).
3. Click **Send for Review** to submit your request for Apple to review your account. Apple will review your account to verify if it meets the standards for customer interaction.
4. Once you submit your profile, a confirmation message is displayed, as shown in the below screenshot.
• If you do not have any alerts, the status area on the profile page shows that Your request has been sent and is being reviewed by Apple.
:::note
* If you have any alerts, you need to fix them before you submit your profile for review.
* The approval process may take 1 or 2 business days.
:::
5. Once your account is reviewed by Apple, it will be in an online state.
6. Click on your account, expand the **Links** drop-down, and **Copy ID** to connect your bot.
## Connect ABC channel to your bot
To connect ABC channel to your bot on the platform, follow these steps:
1. On the left navigation bar, click **Extensions**.
2. Click **Channels** > **Messaging** > **Apple Business Chat**.
3. Enter the **Business ID** that you have copied from the Messages for Business Account and click **Save**.
4. Navigate to the **Overview** page, under the **Active channels** section, you can see that the ABC channel is successfully connected to your bot.
## Test your bot on ABC
After connecting your bot to the ABC channel, you can test your bot.
#### Prerequisites
* Ensure that you have created the bot with intents and configured the flows with the same intent. For more information, click [here](https://docs.yellow.ai/docs/platform_concepts/get_started/createfirstbot).
* To test your bot on ABC, you need to **Copy Conversational link** from the Messages for Business Account.
To test your bot on ABC, follow these steps:
1. Paste the conversational link that you have copied from the Messages for Business Account in the address bar and click enter.
2. Enable the checkbox and click **Open Messages**.
3. Start the conversation to test your bot.
---
## Alexa
Integrating Amazon Alexa with the Yellow.ai bot enables businesses to build voice-enabled experiences for their customers. This integration allows users to interact with the bot using Alexa-powered devices, offering a hands-free, conversational interface for customer support, information retrieval, and task automation.
Alexa skill consists of two components:
1. [Voice User Interface (VUI)](https://developer.amazon.com/en-US/docs/alexa/custom-skills/define-the-interaction-model-in-json-and-text.html): This is where you define how to handle a user's voice input.
2. [Amazon Developer Portal](https://www.amazon.com/ap/signin?openid.pape.preferred_auth_policies=Singlefactor&clientContext=133-4657237-7550651&openid.pape.max_auth_age=7200000&openid.return_to=https%3A%2F%2Fdeveloper.amazon.com%2Falexa%2Fconsole%2Fask&openid.identity=http%3A%2F%2Fspecs.openid.net%2Fauth%2F2.0%2Fidentifier_select&openid.assoc_handle=amzn_dante_us&openid.mode=checkid_setup&marketPlaceId=ATVPDKIKX0DER&openid.claimed_id=http%3A%2F%2Fspecs.openid.net%2Fauth%2F2.0%2Fidentifier_select&openid.ns=http%3A%2F%2Fspecs.openid.net%2Fauth%2F2.0&#/skills): The backend logic on the Yellow.ai [Platform](https://app.yellowmessenger.com) that determines bot responses.
## Setting up Your Alexa skill in the Developer Portal
1. Login to your [Amazon Developer Portal](https://developer.amazon.com/).
2. Navigate **Developer Console** and click **Alexa** > **Alexa Skills Kit**.
4. Create Alexa Skill
1. Click **Create Skill** to begin with creating a new Alexa skill.
2. Build a skill using the instructions provides on [Alexa Documentation](https://developer.amazon.com/en-US/docs/alexa/custom-skills/steps-to-build-a-custom-skill.html).
3. Use the Custom Interaction Model and set the primary language.
4. Define Skill information
* **Skill Type** - Create all skills using the Custom Interaction Model. This is the default choice.
* **Language** - Choose the first language you want to support. You can add additional languages in the future. For now, set it to English(India).
* **Name** - This is the name that will be shown in the Alexa Skills Store, and the name your users will refer to.
* **Invocation Name** - This is the name that your users will need to say to start your skill. We have provided some common issues
developers encounter in the list below, but you should also review the entire [Invocation Name Requirements](https://developer.amazon.com/en-US/docs/alexa/custom-skills/choose-the-invocation-name-for-a-custom-skill.html).
5. Define an Intent for Sending Text to the Chatbot Configure Interaction Model
1. Click the **Continue with template** to move to the Interaction Model.
2. In the **Skill Builder Checklist**, complete the necessary fields.
6. Create a Custom Slot Type
1. Navigate to Slot Types (0) from the menu.
2. Click **ADD+** to create a new slot type.
3. Name it *FreeText* and provide common utterances.
4. Enter 10-15 common utterances that users might say to the chatbot.
7. Define an Intent for Sending Text to the Chatbot
1. In the **Intents** section, click **ADD+** to create a new intent.
2. Name the intent *RawText*.
3. Select "RawText" from the left panel and navigate to Intent Slots on the right side.
4. Create a new intent called **RawText** and add an intent slot **RawTextData**, linking it to the **FreeText** slot type.
5. Define sample utterances such as `{RawTextData}` to send raw user input to the backend. 
8. Build & Configure the Model
1. Click **Build Model** in the top menu.
2. Once the model is successfully built, go to Configuration.
3. Select Endpoint from the menu.
4. Choose HTTPS as the Service Endpoint Type.
5. Enter the following URL in the Default Endpoint: `https://cloud.yellowmessenger.com/integrations/alexa/getResponse`
9. Set Up Permissions & SSL Certificate
1. If your skill requires device location access, refer to Amazon's Device Address API. [Click for more details](https://developer.amazon.com/docs/custom-skills/device-address-api.html)
2. Under SSL Certificate Settings, select the second option as shown in the reference image.
## Link Alexa to Yellow.ai Bot
1. On your Alexa Developer Console Navigate to Skill Information and copy the Application ID (e.g., amzn1.ask.skill.111ffc3d-229f-46f7-b537-0c19bf89aca2).
2. Open the Yellow.ai Cloud Platform and go to **Extensions.** > **Channels** and select **Alexa**.
3. In Alexa skill ID, enter skill ID (example: mzn1.ask.skill.111ffc3d-229f-46f7-b537-0c19bf89aca1).
4. Click **Save**.
---
## Android push notifications
## Configure Android push notification
### Step 1: Add project to FCM & generate private key
1. Log on to the [Firebase Developer Console](https://console.firebase.google.com/) and add Firebase to your [Android app](https://firebase.google.com/docs/android/setup).
2. In Project settings, navigate to **Service accounts**.
3. Click on **Generate new private key**. A JSON file will be downloaded which contains all the credentials.
:::info
To set up Firebase Cloud Messaging client app on Android, see the [Firebase official documentation](https://firebase.google.com/docs/cloud-messaging/android/client).
:::
### Step 2: Add key to Yellow.ai
Once you get the key JSON file, upload the key on Yellow.ai to establish a connection and grant access to send push notifications from Yellow.ai.
To connect FCM to yellow.ai, follow these steps:
1. On the left navigation bar, click **Extensions**.
2. Click **Channels** > **Push Notifications** > **Android (FCM)**.
3. Click **+ Connect your account**.
4. Cick **Upload** and choose the downloaded JSON file from your local folder and click **Add**.
:::note
To know how to create a push notification campaign, see [Mobile push template](/docs/platform_concepts/engagement/outbound/templates/mobilepush.md).
:::
## Code snippets for Android Push notifications
Notifications are sent to Firebase which then pushes them to the app using the user's device token. This section provides payloads that are sent to Firebase for different on-tap actions (action performed when the user taps on the push notification).
The following table provides descriptions of different parameters:
Parameter | Datatype | Description
--------- | -------- | ---------
notification | Object | Details of the notification
title | String | Title of the notification.
body | String | Content of the notification.
payload | String | Contains additional parameters such as image, botId, deeplink and journeySlug.
botId | String | The bot ID for which the notification has been triggered.
image | String | Path of the image file or URL of the image.
deeplink | String | URL which redirects the user to a particular page of the application.
journeySlug | String | The name of the journey which has to be triggered in the bot, when the user taps on the notification
token* | String | A unique identifier or device ID generated for the operating system and specific device. Notifications are sent to the user's device ID.
:::note
* Parameters with * are mandatory.
* Either `deviceToken` or `ymAuthToken` is needed. For campaigns, `deviceToken` is mandatory and `ymAuthToken` is optional. However, to push notifications from from your app to User 360, only `ymAuthToken` is required.
* Ensure you create users along with their device and ym authentication tokens.
* When sending out notifications, the yellow.ai consumes these details automatically, decides the platform, and sends out notifications accordingly.
:::
### Notification without custom action
This is used to redirect to the main activity of the app when a user clicks on the notification - On tap action, open the app (your app). See Step 7 of [Push notification template](/docs/platform_concepts/engagement/outbound/templates/mobilepush).
We do not send any payload, instead, we just trigger the notification containing the title and body along with the image (if included). There is no action included in the payload.
```js
{
"notification": {
"title": "Hey there",
"body": "Body",
"image": "{ImageUrl}"
},
"token": "{deviceToken}"
}
```
### Notification with deep link
This is used for the On tap action to open a deep link to the app - when a user clicks on the notification, it redirects to a specific screen of the app where the deeplink is pointing to.
The payload consists of the standard notification details (title, body, and image) along with the `botId` and `deeplink` URI.
```js
{
"notification": {
"title": "Hey there",
"body": "Body",
"image": "{imageUrl}"
},
"data": {
"botId": {botId},
"deeplink": "{uri}"
},
"token": "{deviceToken}"
}
```
### Notification with bot response
This is used for the On tap action to open a specific bot flow - when a user clicks on the notification, it opens the bot that can [trigger a specific bot flow](#payload-to-trigger-bot-flow) or [shows a predefined response](#payload-to-open-the-bot-with-a-predefined-response).
#### Payload to trigger bot flow
Here is the payload to trigger a specific bot flow when the user clicks on the notification.
```js
{
"notification": {
"title": "Hey there",
"body": "Body",
"image": "{imageUrl}"
},
"data": {
"botId": "{botId}",
"journeySlug": "{slug}"
},
"token": "{deviceToken}"
}
```
#### Payload to open the bot with a predefined response
Here is the payload to show a specific bot response (text message) when the user clicks on the notification.
It just contains `botId` in the response under the `data` parameter.
```js
{
"notification": {
"title": "Hey there",
"body": "Body",
"image": "{imageUrl}"
},
"data": {
"botId": "{botId}",
},
"token": "{deviceToken}"
}
```
## Implementation codes for Android app developer
The following are the code snippets for the Android app developer to get the notifications and handle different scenarios.
### Fetch additional data from notifications when clicked
Use the following code snippet fetch additional information from the user when the user clicks on the notification.
```js
HashMap < String, Object > payloadData = new HashMap < > ();
HashMap < String, Object > botPayloadData = new HashMap < > ();
Bundle bundle = getIntent().getExtras();
if (bundle != null) {
String tmp = "";
for (String key: bundle.keySet()) {
Object value = bundle.get(key);
payloadData.put(key, value);
tmp += key + ": " + value + "\n\n";
}
mTextView.setText(tmp);
}
```
### Start chatbot with bot details and additional data
Use the following code snippet to open the bot and trigger a specific bot flow when the user clicks on the notification.
```js
if (payloadData.get("botId") != null) {
String botId = (String) payloadData.get("botId");
YMChat ymChat = YMChat.getInstance();
ymChat.config = new YMConfig(botId);
ymChat.config.version = 2;
ymChat.config.ymAuthenticationToken = "2gs20emoof1666164936076";
if (payloadData.get("journeySlug") != null) {
String journeySlug = (String) payloadData.get("journeySlug");
botPayloadData.put("JourneySlug", journeySlug);
ymChat.config.payload = botPayloadData;
}
try {
ymChat.startChatbot(this);
} catch (Exception e) {
e.printStackTrace();
}
}
```
### Handle notifications in the foreground when the bot is closed
Use the following code snippet to handle the notifications you receive when the app is open in the foreground.
```js
class MyFirebaseMessagingService: FirebaseMessagingService() {
final
var TAG: String = "YMLog"
override fun onMessageReceived(remoteMessage: RemoteMessage) {
Log.i(TAG + " Remote message", remoteMessage.toString())
Log.i(TAG + " Remote message", remoteMessage.data.toString())
super.onMessageReceived(remoteMessage)
}
}
```
:::info
For more details regarding the integration, see
* [Android SDK documentation](https://docs.yellow.ai/docs/platform_concepts/mobile/chatbot/android).
* [Test app with Android SDK and Firebase integration](https://github.com/yellowmessenger/YmChatBot-Android-DemoApp)
:::
---
## Channels FAQs
### WhatsApp chatbot related FAQs
Why should you use the WhatsApp chatbot channel?
WhatsApp chatbots is one of the fastest growing chatbot messaging channels today. It gives brands a great potential to reach out, enagage and support their customers on the channel consumers are.
What can a customer share on WhatsApp chatbot?
- A simple text message- An image in JPEG or PNG format - An audio recording, video or GIF - Can attach a document in PDF or docx format - Can attach a contact or location
In what ways can a WhatsApp chatbot respond?
- A simple text message- An image in JPEG or PNG format - An audio recording, video - Can attach a document in PDF or docx format - Can attach a contact (via API) or location
What is not possible with WhatsApp chatbot today?
- Cannot send promotional or marketing notifications.- Does not have ‘buttons’ option during conversations. - Cannot send notifications without getting opt-in consent.
What is a conversation?
A single conversation is an exchange messages within 24 hours between a user and the chatbot.
What is a notification?
Notification is an outbound message (chatbot-initiated) sent by the chatbot to a particular WhatsApp user.
What is the difference between a notification and a conversation?
A conversation is an exchange of messages between the chatbot and a user, initiated either by the user or the chatbot. Notification triggers chatbot-initiated conversation.
Is it possible to send marketing or promotional notifications on WhatsApp?
No, in order to send a regular notification, the user's opt-in is required.
Are buttons allowed within the conversation?
No, WhatsApp can approve a button that is included in a notification template.
What is a template?
A template is a notification message that needs to be approved before it is sent to users.
What is the pricing model of WhatsApp?
Refer to WhatsApp Pricing
Can WhatsApp chat bot support multiple languages?
Yes, the WhatsApp chatbot can support multiple languages during conversations. For notifications, while sending for approval, we can opt for required languages.
Is there a restriction on WhatsApp for any location or country?
WhatsApp chatbot is applicable in all the regions where WhatsApp channel is currently operating.
What are the top use cases brands can leverage the WhatsApp chatbot for?
WhatsApp chatbot will be useful for proactive notification-based outreach, timely reminders, engaging suggestions on products or services, sales and support.
What is the commerce or business policy of WhatsApp?
The updated commerce policy can be found here. The updated business policy can be found here
Is it possible to connect two phone numbers associated with different business manager accounts to a single bot?
You cannot connect two phone numbers of different WABA or Facebook business manager to a single bot.
Is it possible to remove the current WABA number and link to the new WABA or FBM?
WABA numbers cannot be migrated from one BM (Business Manager) to another. It can only be migrated from one BSP (Business Service Provider) to another, or from one WABA to another, by retrieving the same BM ID attached to both WABAs
Is it possible to change the color of the email ID to black in WhatsApp chatbot?
No. By default, the email address is blue in color.
Is the speech-to-text (STT) feature supported in WhatsApp?
No, the STT feature is not supported for WhatsApp.
Can we have multiple bots in a single subscription, with different WABAs connected to each?
Yes, you can have multiple bots under a single subscription, and each bot can have a different WABA connected to it. It is also possible to have multiple numbers connected to a single bot, but all the numbers have to be under the same WABA ID in this case.
Is it possible to select multiple answers at once on a WhatsApp channel using the quick reply button?
WhatsApp does not support Multi select in list or button messages. You can use the Multi Select prompt, which displays the options in the form of a text message, to share the options via text. For example, the bot shared a few options with 1, 2, 3, 4, and so on. and the user has to respond back with the selection as 1 or 3 in a specific accepted format to validate and get the user's selection. This is a workaround that is used in the case of WhatsApp.
Does WhatsApp support sharing locations?
Yes, users can share their location by clicking this 📎 icon on WhatsApp and sharing their current location. The bot will receive the latitude and longitude of the user, based on which the user's location can be identified. Note that live location sharing won't work for this case.
Is it possible to display a thumbnail from an URL in WhatsApp?
Yes, WhatsApp will render URLs with thumbnails, and you will be able to preview them. URL previews are rendered in the following cases: • The business has sent a message template to the user. • The user initiates a conversation with a Click to chat link. • The user adds the business phone number to their address book and initiates a conversation.
How to configure welcome message for WhatsApp?
The welcome message will not be displayed automatically in WhatsApp. You need to train an intent with “hi” or “hello” and configure it in a journey to trigger the flow.
### Facebook (FB) Messenger chatbot related FAQs
What can a user share on FBM chatbot?
- A simple text message- An image in JPEG or PNG format - A video, an audio or a sticker - A GIF or an emoji
In what ways can a FBM chatbot respond?
- A simple text message- An image in JPEG or PNG format - A video or GIF - Can attach files in PDF or docx format - Can share card or card carousel - Can trigger Quick reply buttons for users to click - Via various message template
What is not possible with FBM chatbot today?
Cannot send notification before the user initiates the conversation.
What is a standard message?
One conversation is an exchange of messages within 24 hours between one user and the chatbot.
What is a one-time notification?
Notification is an outbound message (chatbot-initiated) sent by the chatbot to a particular Facebook Messenger user outside the 24-hour window if the user opts-in for the same.
What is a private reply?
When an FB user comments or makes a visitor post, the brand can privately reply to the user on the FBM in context with the user inquiry.
Is it possible to send marketing or promotional messages on FBM?
The promotional message can be sent as a standard message within a 24-hour window. To send promotional messages outside a 24-hour window, "sponsored messages" will be useful.
What is a message template?
A message template is a predefined message structure that is convenient to showcase products, receipts, and so on. To know more, click here
What is the pricing model of FBM chatbot?
Contact [support](mailto:support@yellow.ai) for pricing information.
Can FBM chat bot support multiple languages?
Yes, the FBM chatbot can support multiple languages.
How to get onboarded to FBM chatbot and what are the prerequisites?
Refer this document
How to make users discover and start using your brand’s chatbot?
Some discovery points include: * Drop the CTA to FBM chatbot on the brand’s webpage * Sponsored ads to FBM chatbot CTA * Organic posts to FBM chatbot CTA * FB or Instagram posts having Messenger chatbot CTA
What all are the potential use-cases of FBM chatbot?
Timely reminders on carts and payments, sales and support, and proactive suggestions are some good usecases.
Does the Facebook channel support WebView?
No, the Facebook channel does not support WebView.
How can we share a location on Facebook Messenger?
It is not possible to directly share a location in Facebook Messenger. However, there is an alternative approach you can take:• Ask for City/Zip Code: Instead of sharing the location directly, you can prompt the user to provide their city, zip code, or any other relevant location information.• Use Geolocation API: Once the user provides the location information, you can use the Geolocation API to retrieve the coordinates or specific details about that location.
Is it possible to get the user’s mobile number in the WhatsApp channel?
Yes, to get the mobile number when a user is connected to the bot, you need to use a system variable called sender as shown below.
`{{{sender}}}`
Is it possible to get user details through payload in the Facebook Messenger bot?
Currently, you can retrieve the name and profile picture (if available) for Facebook users using the payload.
### Google Business Messaging (GBM) chatbot related FAQs
Why do we need GBM chatbot channel?
The first thing we do when we look for some product or service is to 'Google them'. 90% of overall search traffic globally is using Google. The ability to engage with the potential customers right then when they search is powerful. In other words, GBM helps with fantastic Discovery-to-Engagement.
What can a user share on GBM chatbot?
- A simple text message- An image in JPEG or PNG format
In what ways can a GBM chatbot respond?
- A simple text message - An image in JPEG or PNG format - Can send URLs to files of PDF or docx - Can share interactive cards about products or service offerings - Can trigger Quick reply buttons for users to click
What is not possible with GBM chatbot today?
- The GBM chatbot is not supported in desktop or laptop view but only on mobile phones. - Videos cannot be embedded. Any type of custom, for example, a Slider or dropdown is not available. - The Thumbview or preview link is not possible through GBM chatbot.
Which industries are allowed to use GBM?
Please go through this document for detailed industry-wise solution
Is there a restriction on GBM for any location or country?
There is no restriction on location or countries where the product would not work yet.
Where can I find data and security details?
Click here
Does a brand need to have a specific location mapped to the Google My Business account to use GBM?
For time being, countries except for the US, a brand must have a verified location associated with its Google My Business Account to use GBM.
How much time would it take to deploy a chatbot for a customer in GBM?
If the bot is ready (Changes to be made for GBM specific bot) and the pre-requisite to onboard a customer is available, the whole process from registration to verification till launch with relevant Google and Brand approval should be tentatively around 3-4 business days in an ideal scenario.
Can GBM support Multiple languages?
The multi-language support is not there in the shell of the product for example, the CSAT score popup. Also, a welcome message will have to be in English. But if the bot is multilingual it can handle the language conversation in different languages during conversation messages.
What is the pricing model of GBM?
Contact [support](mailto:support@yellow.ai) for pricing information.
What are all the discovery points of GBM chatbot channel?
These are the possible entry points to GBM channel.
## General FAQs
What is session timeout?
A session lasts for 24 hours and includes any number of interactions the user has in a 24-hour window from the start of the session.
What is session duration?
Session duration is based on the time of each user response. It resets if there is a 30-minute gap between responses. The total session duration is the sum of all user response times.
---
## Limitations and best practices of chat widget and mobile SDK
This guide contains the character limits for Chat widget and Mobile SDK.
## 1. Quick Reply
The following are the character limits for Quick Reply (QR) options:
| Quick reply options | Character limit |
|---------------------|-----------------|
| Quick reply button | There is no character limit for QR buttons. |
| Quick replies | There is no limit on the number of QRs in a single step. |
## 2. Text field
| Text field options | Character limit |
|---------------------|-----------------|
| Multi-line input | Limited to 1024 characters when multi-line input is enabled. **Note:** Multi-line input will be available by default for all bots in the future.  |
## 3. Cards/Carousels
| Cards/Carousels options | Character limit |
|---------------------|-----------------|
| Single card | There is no limit to the number of buttons in a single card.  |
| Buttons | There is no limit on the number of characters in each button (both name and text).  |
| Title | There is no limit on characters in the title.  |
| Carousel card | In Builder, there is a limit of 10 cards in a single carousel (there is no limit when these are generated via API). The recommended dimensions for carousel images: Width - 248px and Height - 164.2px.  |
| Description | There is no limit on characters in the description.  |
## 4. Multi select
| Multi select | Character limit |
|---------------------|-----------------|
| Options | There is no limit on the number of options in multi-select.  |
| Characters | There is no limit on the number of characters used in each option. |
* **File upload:** The maximum file size is 20 MB.
---
## Fetch Chat widget history
Chat history is a series of conversations that have happened between a user and an AI-agent. The chat history includes details such as user’s input, AI-agent responses, and the date and time of the conversation.
Chat history retrieves past conversations that tailor future interactions. It helps the AI-agent to analyse the user’s inputs and provide accurate automated responses to the user’s queries. Thereby, it improves the overall efficiency and reliability of the AI-agent.
Let's say that you want to fetch a user's chat history from an AI-agent. To do so, you need to pass a unique identifier, the ymAuthentication token, via an AI-agent script, payload, or init function.
:::note
* Ensure that the ymAuthentication token is secured and only authorized users can access it.
* Chat history can be retained for a maximum duration of 6 months.
* Ensure that ymAuthenticationToken is passed in string format.
:::
In this article, you will learn:
* [How to pass ymAuthentication token for a chat widget?](#1-pass-ymauthentication-for-a-chat-widget)
**Prerequisites to pass ymAuthentication token:**
Before you passing the ymAuthentication token via the script, payload, or init function, you need to enable **Show history of the conversation** in the **Settings** page.
:::note
When the "Create New Tab session" flag is enabled, history will not be retained on page refresh even if "Show History" is set to true and the ymAuthenticationToken is passed.
:::
To enable "Show history of the conversation", follow these steps:
1. On the left navigation bar, click **Extensions**.
2. Click on **Chat widget**.
3. The Chat widget screen appears as shown below.
4. Navigate to the **Settings** tab, expand **Chat history** and enable **Show history of the conversation**.
## 1. Pass ymAuthentication for a chat widget
Chat history is fetched with the help of a unique token generated for each user who logs into your platform. Once this token is generated, you can verify if a user has been authenticated.
### 1.1 Pass ymAuthentication token via script
To pass ymAuthentication token via script, follow these steps:
1. On the left navigation bar, click **Extensions**.
2. Click on **Chat widget**.
3. The Chat widget screen appears as shown below.
4. Navigate to the **Deploy > Web > COPY CODE TO Install bot**. A bot script is copied.
**Sample bot script:**
```c
```
To fetch the user's chat history from a AI-agent, add the **ymAuthentication** token in the following AI-agent script:
```c
```
### 1.2 Pass ymAuthentication token via init function
To fetch the chat history, pass the ymAuthentication token in the below init function:
```
window.YellowMessengerPlugin.init({
ymAuthenticationToken: 'Your_Unique_token'
});
```
### 1.3 Pass ymAuthentication token for PWA bot
You can fetch the user's chat history from a PWA bot by passing the ymAuthentication token.
To pass the ymAuthentication token for a PWA bot, follow these steps:
1. Use this `https://cloud.yellow.ai/pwa/v2/live/x1657623696077` URL.
2. In the address bar, append `?ymAuthenticationToken=12345`.
For example, `https://cloud.yellow.ai/pwa/v2/live/x1657623696077?ymAuthenticationToken=12345`
3. Refresh the page to view the chat history.
---
## Chat separator
A chat separator is used to separate the conversations between an agent and a user in a chat widget. This helps you identify when the user is connected or disconnected to a live agent.
A chat separator is displayed when the following actions are performed:
* When an agent is connected to the bot, a divider is displayed along with the message `"{agent name} has joined the conversation"`. Click [here](https://docs.yellow.ai/docs/platform_concepts/inbox/inbox_setup/inboxdemo#1-implement-live-chat) for more information on how to connect an agent to the bot.
* When you are closing the ticket/connecting back to the bot, a divider is displayed along with the message "`{agent name} has left the conversation`". Click [here](https://docs.yellow.ai/docs/platform_concepts/inbox/inbox_setup/inboxdemo#tab-2-live-chat-request-and-resolution-on-the-inbox-chat-screen) for more information on how to close the ticket.
---
## Chat widget components
The platform allows you to add components to the chat widget so that the user experience is not limited to plain text.
There are two types of components - **Interactive** and **Non-Intercative**. Click [here](https://docs.yellow.ai/docs/platform_concepts/channelConfiguration/character-limits-sdk) to know more about the limitations of the components.
Let's take an example, where you want to register for an online class through a website. With the help of date and time picker components in the chatbot, you can register quickly by providing the appropriate date and time instead of manually typing the text messages.
:::note
Each of these components supports both light and drak back ground theme.
:::
## 1. Interactive messages
This type of message allows you to make a quicker selection from a menu when interacting with a bot. It allows the user to actively interact with the chatbot by clicking buttons, menus, or custom actions.
Following are the types of interactive message components:
### 1.1 Quick replies
| | |
|---------|-------|
| This component allows you to reply to the bot with the pre-defined buttons. When your user clicks on any of the quick reply buttons, a message is sent into the conversation. Click here to implement Quick replies using a node. |
### 1.2 Multi select
| | |
|---------|-------|
| This is similar to quick replies. It consists of multiple quick reply buttons where the user can select multiple options at once to send the response to the chatbot. Click here to implement Multi-select using a node. • **Limitation**: You can configure upto 100 options. |
### 1.3 Date picker
| | |
|---------|-------|
| Allows you to select a preferred date from the calendar view. The date is displayed in the predefined format. If the user's input contains a date or a time, it will pass the validator. Otherwise, the specified validation fail message will be sent. Click here to implement Date picker using a node. |
The following are the different date pickers supported:
| options | Description |
|--------|-----------|
| **Single date picker** | Allows a user to select a single date from a calendar. |
| **Range date picker** | Allows a user to select a start and end date from a calendar. |
**Month date picker** | Allows a user to select a month from the date picker. |
**Simple date and time picker** | Allows a user to select a date and time, which is in the pre-defined format. |
**Time picker** | Allows a user to add time to the conversation. |
### 1.4 Cards
This component uses UI annotations to display concise information related to a specific context in a limited-space container using images, buttons, and links to download attachments. Click here to implement cards using a code-based approach.
The following are some key features of cards:
* Provide a richer experience in chatbot conversations when compared to text based messages.
* Display information in the widget so your users get direct insights into their queries without switching screens.
Following are the different types of interactive cards:
Cards | Description
------|-------
**List card** (Generic card) | Displays lists of records that are related to the specific queries.
**Product card** | Provides all the detailed information about your product, such as the product name, image, variants, and description.
**Slider card** | Allows you to choose the minimum and maximum value within the defined range by sliding the pointer.
**Multi select transaction card** | Allows you to view multiple transaction details at a time. Each of the transactions contains details such as title, amount, account number, time, and status. With this card, you can perform the following actions: • **Select:** Enable the checkbox to select one or more transactions from the list. • **Load more:** Displays up to 5 transactions at a time. To view the next set of transactions from the current list, click on **Load more** button. • **Submit:** You can submit the selected transactions to the bot by clicking the **Submit** button. Note that, **Submit** and **Load more** buttons are disabled once the transactions are submitted. **Limitations:**• A maximum of 50 characters is supported for the title.• This card is compatible with all widget modes, including PWA, SDK, and Web widget. • It supports an icon or a fallback avatar for each transaction. • You cannot customize the card title, and there is no restriction on the number of options you can add.
**Single select transaction card** | You can use this card when you want your users to select a single transaction from the list. For example, to see transaction details. When you enable Single select transaction card, bot users can select one transaction from the list and click on **Submit**. By default, it shows up to five transactions. To view the next set of transactions, users can use **Load more**. Note that, **Submit** and **Load more** buttons will be disabled once the user clicks on **Submit**. Limitations: • A maximum of 50 characters is supported for title.
### 1.5 Media
This component allows you to add images, videos, and files to the bot conversation.
| Video | Image | File|
--------|-------|-----|
| |
:::note
You can download video, image, and file sent by the bot or agent.
:::
### 1.6 Feedback
| | |
|---------|-------|
| This feature allows you to collect user feedback. Feedback is collected based on the user's interaction with the chatbot or live agent at the end of the conversation. The feedback component has two options (:thumbsup: or :thumbsdown:) and star rating. Additionally, there is an optional text field to capture detailed feedback through text input. Users have the flexibility to skip any step of the feedback process. You can collect feedback through the following options: 1. **(:thumbsup: or :thumbsdown:)**The thumbs up or down options enable users to provide positive or negative feedback. Additionally, they can include comments based on their feedback selection. • Use this option to capture whether the user has liked or disliked the overall conversation. • You can configure the positive and negative feedback options according to your business needs. 2. **Star rating** This option allows users to rate their experience on a scale of 1 to 5. Depending on the rating, the following actions will be displayed: • Ratings 1 to 3 redirect users to a page with up to 5 predefined negative feedback options. • Ratings 4 to 5 redirect users to a page with up to 5 predefined positive feedback options. Click here to implement Feedback using a node. | |
### 1.7 Location
| |
|------|
| This component enables your bot users to search, select, or share location access using Google Maps. With this component, you can perform the following actions: • **Share location**: This enables you to share your current location. • **Map**: Expand the map view to pinpoint and select the desired location. Note that this function is not available on iOS devices. • **Search for location**: Search for a specific location you wish to share. The component will start displaying suggestions as users type. • **Confirm:** You can confirm the selected location by clicking the **Confirm** button. • **Cancel**: To close the map view, click the **Cancel** button. • **Go back**: Click this button to go back to the Share location option. Click here to implement Location using a node. |
![](https://i.imgur.com/OpiPYhl.png")
### 1.8 Attachment
| | |
|---------|-------|
| This component allows you to upload documents, images, and other files from their device or from a cloud storage provider. |
### 1.9 Home button
| | |
|---------|-------|
| This component allows you to refresh a chatbot or to trigger a conversational flow. |
### 1.10 Upload file
| | |
|---------|-------|
| This component allows you to upload files in supported formats such as jpeg, jpg, png, gif, pdf, txt, doc, ppt, docx, pptx, xlsx, mp4, mp3, and mov. You can either attach a file or skip it. Click here to implement Location using a node. |
### 1.11 Callout banner
| | |
|---------|-------|
| A callout banner allows you to add a banner to the chatbot's conversation. It can be used to alert users about new products, services, special offers, and promotions. When multiple banners are configured for a chatbot, the banners are automatically scrolled every five seconds. You can also add the images to the callout banner. For more information on how to add the images to the callout banner, click here. Note that, the banner with an image cannot have buttons in it. Brands can select the close, or minimise button for banners. Upon minimising, users can later access the banner by clicking on the expand button. The user’s last selection is retained on page reload. You can trigger a flow or redirect users to a page or URL in the banner. Also, you can add a title to the banner when it is minimised (this is optional). **Limitations:**• You can add up to 4 banners with text or image.• Each callout banner supports two buttons with up to 24 characters each.• The callout banner supports 200 characters in the title.• You can add up to 2 buttons to the text banner.• Supported image size is 10MB. In the case of images, the width may vary, but the height remains fixed at 113 pixels. **Note:** You cannot add videos or GIFs to the callout banner.|
## 2. Non-interactive messages
This type of message does not require a response from your bot user by clicking the buttons, menus, or custom actions. A Chabot uses this type of message to generate automated response with all the details related to your queries.
Following are the types of non-interactive message components:
Components | Description
------|-------
**Contact card** | This component displays the information of the user and allows you to communicate with the user through email, phone, or WhatsApp.
**Order status** | This component is used to track the status of your order with details such as order Id, delivery date, and total amount.
**Transaction status** | This component is used to track the status of your transactions.
**Receipt card** | This component is used to display transaction or purchase-related details such as fixed deposit amount, interest rate, title, and reference ID. With this card, you can perform the following action:• **Submit**: Sends title header text and title header value data to the bot.
---
## Chat widget alerts and error messages
When a user interacts with the chat widget, they may encounter different types of error messages based on the type of error.
The table provides all the possible errors with descriptions:
Errors | Description
-------|------------
File upload limit | You can upload files with a maximum size of 20 MB. This error occurs when you try to upload files that exceed this limit.
Network disconnected | When the AI-agent users are disconnected from the internet, the AI-agent notifies them and provides an option to reload the page.**Note:** If network connection is re-established, the AI-agent will again connect to the internet without having to reload.
Network error | This error occurs when the chat widget is disconnected from the internet while sending a message, uploading a file, or selecting quick replies.
Input bar typing limit | Displays a message when users reach the maximum limit of 500 or 1024 characters. If the user exceeds this limit or attempts to paste more than the maximum allowed characters, the system will prevent them from typing or pasting additional characters. **Note:**• If the user reaches the maximum limit of 1024 characters for multi-line input, then **You have reached maximum character limit of 1024** error message is displayed, and this is enabled via AI-agent mapping.• If the user reaches the maximum limit of 500 characters for single-line input, then **You have reached maximum character limit of 500** error message is displayed, and this is enabled via AI-agent mapping.
Platform down time error | Displays a message when platform is experiencing a downtime due to maintenance activities, server downtime, or unexpected technical failures.
File type error | Displays an error when you try to upload unsupported file type formats such as documents, images, and other files. The supported file type formats are JPG, PNG, GIF, MPV4, PDF, MOV, HEVC, DOCX, PPTX, XLSX, MP3, OGA, and AMR.
File upload limit | Displays an error when you try to upload more than five files at a time.
---
## Chat widget FAQs
## Setup page related FAQs
Chatbot is auto-scrolling upwards after navigating to a different tab by clicking the URL from the chatbot. How to resolve this issue?
You need to enable the "Scroll the chat window to the bottom" option in the Chat widget's Settings tab. Navigate to the Channels > Chat widget > Settings.
How to enable chat history conversation?
For cloud.yellow.ai platform, ensure that Show history of the conversation is enabled.
For `app.yellowmessenger.com` or `app.yellow.ai` platform, ensure that Reset Context for every load checkbox is unchecked in the dashboard settings.
Note: If you want to maintain a history across devices or browsers, you can create an authentication token, which is a unique token, and pass it in the given format, as shown below:
```javascript
if (userIsAuthenticated) {
// replace this with your own auth logic and reload the bot with new info.
window.YellowMessengerPlugin.init({
ymAuthenticationToken: 'Your_Unique_token'
});
window.YellowMessengerPlugin.show(); // display the bot icon
}
```
Is it possible to change the chat widget background colour for bot and agent messages?
No, the background colour can be changed only for user messages. This can be done by updating the complimentary color in the chat widget settings.
How to change the font size in the widget?
To change the font size in the widget, follow these steps:
1. Navigate to Channels > Chat widget > Widget panel.
2. Expand Font drop-down and select your preferred font size and click Save changes.
Can we change the color scheme of the chat header gradient from top to bottom?
The gradient is intentionally applied from left to right for readability reasons. Applying the gradient from top to bottom might make it challenging to read the text - title & description due to multiple colors. This design decision ensures optimal visibility and a better user experience.
Is it possible to block the users from uploading specific attachment formats?
Yes, you can control which file formats users are allowed to upload for documents, images, and other files. To manage this, navigate to Chat Widget > Settings > Validate attachments
--------
## Chat widget related FAQs
How to resolve a website performance issue after installing the bot?
Ensure that the chatbot script is placed within the <body> tag of the host website rather than the <head>. This will ensure that the bot loads only when the website is fully loaded without affecting its performance.
Why is the bot not displaying or loading any of the configured messages?
Make sure you have configured Welcome message in the Automation. Login to cloud.yellow.ai platform. Navigate to Studio > Welcome Message > Add welcome message. To know more, click here. Also, check the bot status. If the bot is in an unpaused state, it will not load or respond.
Is it possible to deploy two bots on a single website?
No, you cannot deploy 2 bots on a single website.
How to set the position of the bot dynamically?
The bot's position is set to right by default. On the Chat widget settings page, you can change it to left.
To dynamically set the position of the bot on a website, set the position to right on the Settings page and pass `alignLeft:true` inside ymConfig of the chatbot script on the respective webpage.
Does the Chat widget or PWA contain a pop-up component?
No, the pop-up component appears only when an error message such as "device not connected to network" or "file upload limit exceeded" is displayed.
Is drop-down option supported in the Chat widget?
Currently, drop-down is not supported for the Chat widget bot.
Is it possible to integrate the Yellow AI chatbot with a NextJS website?
Yes, you can add the script to any NextJS page. To do so:
* Create a file called `static/yellowai.js` and paste our script. Note: You need to remove the `
)
```
Is the React SDK supported for the web widget?
React SDK is not supported for web widget. However, you can include our script at the end of the body tag in your index.html file.
Is it possible to change the language of the weekdays displayed on the Chat Widget
Yes, the platform supports 10+ languages for placeholder texts such as timestamps, and text fields. The bot user can choose their preferred language to see text in that language.
How to disable the like and dislike buttons shown under the chats in the chat widget (PWA)?
By disabling message feedback in the chat widget, the "like" and "dislike" buttons are disabled.
Is it possible to remove the user's button selection from the list or quick replies in chatbot?
No. Every message exchanged between a bot, users, and agents needs to be tracked/recorded so that the users are aware of the message sent/selection made. Following are the reasons: • Providing feedback: When a user selects an option/sends a message, they expect feedback in response. By displaying the messages, users will know that their message has been received. • Transparency: When a user message is displayed, it builds trust between the user and the chatbot. • Clarification: At times, the bot may not understand the context of the user's message. Displaying the message in such instances will be essential.
Why does a blank space appear when scrolling in the widget?
This happens only for bots migrated from V1 ("app.yellowmessenger.com" or "app.yellow.ai" platform) to V2 (cloud.yellow.ai platform). On the "app.yellowmessenger.com" or "app.yellow.ai" platform, you need to disable "Voice First" for the V2 widget as it is not supported. To disable "Voice First" option, click Configuration > Channels > Chat Widget > General > Voice First.
Is it possible to hide the chat widget icon on the website?
Yes, use "window.YellowMessengerPlugin.hide()" function to hide the icon of the chat widget on the website.
Can we pass data to the widget for every page of the website?
Yes, you can pass the data to the widget on its respective page of the website. For more information, see payload.
Is it possible to configure the position of the bot to be on right when the user selects Arabic and to the left when the user selects English?
Yes, in ymConfig, you must set "alignLeft:true".
How can we change the font color in the bot name and description?
The bot name and description text color is set automatically based on the background color to ensure readability, with a contrast ratio of 4.5+. For example, white text on bright red background is hard to read, so text color is set to black. Slightly darker red shades can be tested to find a readable color combination.
Does the chat widget support HTML tags?
No, the chat widget does not support HTML tags. In order to maintain security and prevent web attacks, HTML tags are blocked within the widget. Any content containing HTML tags will be converted into plain text for display.
Does the chat widget automatically aligns the text based on the selected language?
Yes, the widget automatically aligns the text based on the selected language. For example, English, Hindi, Spanish, and so on are aligned from left to right. Languages like Arabic and Dhivehi are aligned from right to left. Note: If a text message contains both languages, the text will be aligned based on the language set in the bot at the respective step.
Does the chat widget support auto-complete feature?
Yes, the chat widget supports auto-complete. To set up auto-complete, follow these steps:• You need to enable auto complete in [Yellow.ai Platform](https://cloud.yellow.ai) > Channels > Chat widget > Settings > enable Auto complete > click Save changes. For more information, click here• Navigate to Automation > select a flow > click on the respective node > click Make prompt smarter. For more information, click here.
How to disable Message feedback?
By default, message feedback is enabled for all bots. This helps to gather feedback on how helpful bot responses have been to the end user. It is recommended not to disable Message feedback. However, you can disable message feedback from Channels > Chat widget > disable Message feedback > click Save changes.
How to restrict users from clicking on carousel card buttons repeatedly?
Go to Automation > Select the flow > Click on Carousel node > Click Settings icon > Enable Disable action after click
How to deploy a website bot on sites.google.com?
To deploy a website bot on sites.google.com, follow these steps:Navigate to the admin portal of your Google site >
Add an Embed block > Select Embed code > Paste the bot script > Click Next. The bot will be deployed on sites.google.com.
Is it possible to deploy a bot in multiple locations on a website or Mobile SDK?
For web bots, it is not possible to have two bots on the same window simultaneously. However, you can load a default bot initially, and then when a user selects a specific order in which the bot needs to be deployed, you can trigger a new bot using the following code.
`window.YellowMessengerPlugin.init({bot: ''})`
Note that, this will replace the previously loaded bot. On Mobile SDK, if you want to maintain a separate session and history for each order, you need to pass the ymAuthToken parameter. Ensure that these approaches allow you to manage different instances of the bot, but only one bot can be active at a time.
How long will the session be active in the chat widget?
The session in the chat widget will remain active for 24 hours by default. However, if needed, you have the flexibility to customize the session duration from the backend. The session duration can be adjusted within a range of 1 minute to 1440 minutes, which is equivalent to 24 hours. By configuring the session duration according to your specific requirements, you can ensure that users have an adequate amount of time to interact with the chat widget before the session expires. If you have any additional questions or need further assistance, contact our support team
When you receive new messages from a bot or agent, how do you enable scroll behaviour for the chat widget?
Follow the below steps to enable the scroll behaviour. Navigate Channels > Chat widget > Settings > expand General settings > Scroll behaviour.Under Scroll behavior, choose your preferred option:• Bottom: Select this option to scroll the widget automatically to the bottom of the new message.• Top: Select this option to scroll the widget automatically to the top of the new message.• Off: Select this option to disable scrolling, the widget will remain at the same message when a new message is received.
Is it possible to drag the chatbot icon and place it anywhere on the website?
Yes, you need to add floatingIcon: true in the following chat bot script to drag the chatbot icon.
```
```
Is it possible to minimise the callout banner?
Yes, you can minimize it using the icon highlighted in the following:
How to load the callout banner dynamically in the middle of a chat?
A callout banner allows you to add a banner to the chatbot's conversation. Before starting a chat with the user, the callout banner is shown at the top of the chat window with a description of the chatbot’s purpose. To know more, click here.
Banners can be used to alert users about new products, services, special offers, and promotions.
How to load the callout banner dynamically in the middle of a chat?
A callout banner allows you to add a banner to the chatbot's conversation. Before starting a chat with the user, the callout banner is shown at the top of the chat window with a description of the chatbot’s purpose. To know more, click here.
Banners can be used to alert users about new products, services, special offers, and promotions.
If the V1 bot consists of a banner and you want to move to V2 dynamically in the middle of the chat conversation, then you need to add a function to display the same banner in V2.
While migrating from V1 to V2, use the following function code to copy the banner from V1 to V2:
```
return new Promise(async (resolve, reject) => {
try {
app.log(app.profile, "in profile");
if (
app.profile &&
app.profile.payload &&
app.profile.payload.widgetVersion === "v2"
) {
await app.sendEvent({
code: "ui-event-update-promotion",
data: [
{
title: app.renderMessage('indiatour', {}, ''),
options: [
{
title: app.renderMessage('activate_now', {}, 'Activate Now'),
text: "activate channel"
}
]
},
{
title: app.renderMessage('promotion_2', {}, ''),
options: [
{
title: app.renderMessage('download_now', {}, 'Download Now'),
url: "https://watcho.onelink.me/eyNf/4plou2wu"
}
]
},
{
title: app.renderMessage('promotion_3', {}, ''),
options: [
{
title: app.renderMessage('subscribe', {}, 'Subscribe'),
text: 'Subscribe'
}
]
}
]
});
} else {
await app.sendEvent({
code: "ui-event-update-promotion",
data: {
quickReplies: [
{
title: app.renderMessage('indiatour', {}, ''),
options: [
{
title: app.renderMessage('activate_now', {}, 'Activate Now'),
text: "activate channel"
}
]
},
{
title: app.renderMessage('promotion_2', {}, ''),
options: [
{
title: app.renderMessage('download_now', {}, 'Download Now'),
url: "https://watcho.onelink.me/eyNf/4plou2wu"
}
]
},
{
title: app.renderMessage('promotion_3', {}, ''),
options: [
{
title: app.renderMessage('subscribe', {}, 'Subscribe'),
text: 'Subscribe'
}
]
}
],
autoPlay: true,
autoPlaySpeed: "4000",
hide: true,
showPromotionMessage: 'Hi! I am Dia, your d2h Intelligent Assistant.',
displayShowPromotionBar: true
}
});
}
return resolve();
} catch (e) {
app.log(e, 'error in showPromotion');
return resolve();
}
});
```
How to hide the home and input buttons when the user opens the chatbot for first time?
To hide the home and input buttons when the user opens the chatbot, add the setDisableActionsTimeout property inside the window.ymConfig object.
Is it possible to prevent the bot icon from overlapping with CTAs on mobile screens?
The following are the two options to prevent the bot icon from overlapping:
Write a custom script to override the position.
Hide the default icon and create a custom entry point or button on the site.
Use the `window.YellowMessengerPlugin.openBot()` function to open the bot when a user clicks on the custom button. For more information, click here.
Note that the chat bubble and notification icon will not be displayed if a custom icon is deployed.
Can the Bot title, description and logo be changed dynamically based on website?
Yes, you can configure different themes for different websites. Set a default theme in `Channels > Chat Widget > Widget Panel/Bot icon`. Then, based on the user, you can override it on the web and mobile SDK.
For the web, you need to pass the following values inside `window.ymConfig` in the bot script:
```js
window.ymConfig = {
theme: {
botName: "", // Text up to 50 characters
botDesc: "", // Text up to 50 characters
primaryColor: "", // RGB or HEX value
secondaryColor: "", // RGB or HEX value
botIcon: "", // CDN link
botClickIcon: "" // CDN link
}
};
```
Is it possible to replace the close (X) button in the chat widget with a drop-down arrow button?
Yes, it is possible by using a custom script to modify the chat widget’s UI. To implement this change,contact the support team. They can guide you and provide the necessary custom script to help replace the close button with a drop-down arrow.
-----------
## PWA related FAQs
Is it possible to change the short cut icon for PWA bot?
Yes, you can change the PWA bot's shortcut icon via bot mapping. Note that the icons are supported with the following resolutions: * Mobile: 192*192 * Desktop: 512*512.
Is it possible to customise the URL of the PWA bot?
No, you cannot customise the URL of the PWA bot.
Is it possible to pass the data from the URL to a widget?
Yes, using payload, you can pass the data.
Is it possible to integrate the Yellow AI chatbot with a NextJS website?
Yes, you can add the script to any NextJS page, to do so: * Create a file called static/yellowai.js and paste our script. Note: You need to remove the tags. * You can now load this file on page (page name). (jsx|tsx) file
```
export default () => (
)
```
It is possible to automatically open PWA chatbot using chat widget functions?
No, by default PWA bot will be opened automatically.
Why is the date picker not working in the PWA bot, even though it works on the web bot?
The date picker should work in both the PWA and web bots. If it's not working in the PWA bot, check the following: * Channel support: Make sure you are testing on a supported channel. Some channels like WhatsApp do not support the date picker. PWA and Web do support it. * Variable type: Ensure the date is being saved in a variable of type Object. If it is not, the date picker may not function as expected.
----------
## Chat history related FAQs
Is it possible to auto-delete conversations between the user and the bot after 48 hours?
There is no option to delete/hide conversation history after 48 hours. It will be accessible only for 30 days.
How do we add ymAuthenticationToken to the PWA script so that we can see the same chat history in the PWA and mobile SDK?
You need to pass the ymAuthenticationToken in the URL as a query parameter.
`https://cloud.yellow.ai/pwa/v2/live/?ymAuthenticationToken=`
--------
## General FAQs
How to trigger the closeBot() function when a specific flow ends or when you reach a specific node?
You must initiate an event at the end of the specific flow and will receive a callback in onEventFromBot(_ response: YMBotEventResponse) function of YMChatDelegate, where you can add the closeBot.
Is it possible to change the bot title and description when the bot switches from parent bot to child bot?
In orchestrator setup, you cannot interact with the child bot directly, and the UI loaded will be that of the parent bot. Therefore, there cannot be a separate Title, Description, or Icon for the child bot.
What to do if buttons are not loading on the parent website?
This happens when a website blocks CDNs (Content Delivery Network). You need to whitelist these by updating content security policy: * cdn.jsdelivr.net (to load the font) * https://cdn.yellowmessenger.com (to load buttons)
Is speech-to-text (STT) feature supported in the chat widget?
Yes, STT feature is supported for the chat widget.
Is it possible to implement the callout banner for child bots and view them when the parent bot switches to child bots in the app?
Yes, to view the callout banner for child bots, send an event with "ui-event-close-promotion" to close the banner. In this way, you can control when to show or turn off the banner, in this case only for child bots.
Is it possible to remove the user's button selection from the list or quick replies in chatbot?
No. Every message exchanged between a bot, users, and agents needs to be tracked/recorded so that the users are aware of the message sent/selection made. Following are the reasons: • Providing feedback: When a user selects an option/sends a message, they expect feedback in response. By displaying the messages, users will know that their message has been received. • Transparency: When a user message is displayed, it builds trust between the user and the chatbot. • Clarification: At times, the bot may not understand the context of the user's message. Displaying the message in such instances will be essential.
Can we have custom fonts for V2 web bots?
Currently, v2 web bots do not support custom fonts as we need to validate legibility on the chat interface, ensure the availability of appropriate font weights, and then support respective languages. If you need to add a new font, reach out to the support.
Is it possible to display image and text in a single node?
Yes, you can make use of a Generic card and not include any options in it. You need to include an image and a description. Store the function response in a variable of type array and connect it to a message carousel node.
Is it possible to configure customized icons for carousel (card) buttons?
Icons are supported only in quick replies. whereas for buttons inside cards, you can use emojis.
Is it possible to update the token without refreshing the webpage?
No, the token and payload are only fetched during page load. Hence, you cannot update the token automatically.
Even though the agent is not connected to the bot, the app.yellowmessenger.com chatbot displays a green round circle, indicating that the agent is online. Is it possible to change the settings of the bot on the app platform?
Yes, on "app.yellowmessenger.com" or "app.yellow.ai" platform you can disable it in Configuration > Channels > Chat Widget > General > Show Dot Status in Title.
Is it possible to change the language of the bot whenever the user switches from one language to another on the website?
Yes, the language of the bot is changed when a user switches from one language to another on the website. You have to update the bot's language and reinitialize the bot. Note that the language of the chat history cannot be updated, as those messages were already delivered, stored, and fetched from the backend in the respective language.
What are the minimum compatible versions of the browsers supported by the web widget?
• Chrome 89 and later • Edge 89 and later • Firefox 70 and later • Safari 10.1 and later
How to add the image in Quick Replies node?
In the quick reply node, add the image link under the Prefix image. Click here for more information.
When an agent is connected to the bot, is it possible to close the conversation and trigger a journey?
When an agent is connected to the bot, the bot will not trigger any flow. To trigger a particular flow and close the conversation, you need to add the "talk to bot" button in the Callout banner. You can add the button either from the UI or using the function.
**Add talk to bot button using the function**
The following is the sample function:
```json
var array = [{
"title": "Wish to end your chat with our Live Agent",
"options": [
{
"title": "End Chat",
"text": "talk to bot"
}
]
}]
```
event: ui-event-update-promotion
**Add Talk to bot button using Automation's Conversation settings**
To add the banner text for the **talk to bot** button, follow these steps:
1. Navigate to **Studio \> Conversation settings \> Callout banner**.
\
2. Enter the title and button name. Click **Update**.
\\
The callout banner will be updated accordingly.
Is it possible to block users from copying bot them and pasting messages in the text field?
Yes, it is possible to block users from copying bot messages. To implement this, you need to pass `disableCopyPaste: true` inside the the `window.ymConfig` chatbot script.
```js
window.ymConfig = {"bot":"x1657623696077","host":"[https://cloud.yellow.ai](https://cloud.yellow.ai)", "disableCopyPaste": true};
```
How to disable users from clicking on images in the carousel node?
To disable users from clicking on images in the carousel node, include `disableCardImageClick: true` inside the `window.ymConfig` chatbot script.
```js
window.ymConfig = {"bot":"x1657623696077","host":"[https://cloud.yellow.ai](https://cloud.yellow.ai)", "disableCardImageClick": true};
```
Can I hide the chat separator when an agent is connected to the bot?
To hide the chat separator when an agent is connected to the bot, include `hideTransferEvent: true` inside the `window.ymConfig` chatbot script.
```js
window.ymConfig = {"bot":"x1657623696077","host":"[https://cloud.yellow.ai](https://cloud.yellow.ai)", "hideTransferEvent": true };
```
How to retrieve the sender ID on a website if Yellow Messenger authentication is not passed?
To retrieve the sender ID, go to live bot page, right click and select Inspect > Network > Payload search for update API, you can find the userId within the payload.
How can I start a new conversation when my chat has stopped, and the intent is not working?
If your chat has stopped and the intent is not working, try the following steps to start a new conversation:• Click the Home icon – This will reset the conversation and allow you to start fresh.Clear cache – Clearing your browser or app cache can help resolve issues caused by stored session data.
---
## Chat widget supported languages and placeholder texts
The chat widget automatically changes the text based on the user's language preference. It supports multiple languages for placeholder texts, tooltips, and time stamps. For more information on how to set the language, click [here](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/set-language)
:::note
* The chat widget currently supports English, Arabic, Tamil, Kannada, Hindi, Urdu, Slovak, Japanese, Czech, Croatian, Romanian, Polish, Chinese Simplified, Spanish, Portuguese, Telugu, Marathi, Gujarati, Punjabi, Oriya, Malayalam, Bengali, and Assamese.
* Multilingual support is not available for the following::
* Bot name
* Bot description
* Agent name
* When an agent is connected to the bot, the chat separator description is not changed.
* The chat widget automatically detects the script of each message and aligns the text accordingly — no configuration required. Messages written in Arabic are displayed right-to-left (RTL); messages in English, Hindi, Spanish, and other LTR scripts are displayed left-to-right. This applies independently to every message bubble, so a conversation that switches between Arabic and English will align each message correctly.
* If a single message contains both LTR and RTL scripts, the browser's built-in bidirectional text algorithm handles the mixed content automatically.
* Localization is supported only for the placeholder texts whereas for date it is not supported.
:::
## Change your bot language
The chatbot users can change the language of the widget based on thier requirements.
To change the language of your bot, follow these steps:
1. On the left navigation bar, click **Extensions**.
2. Click on **Chat widget**.
3. Go to **Settings**, expand **Configure settings** to enable **Language switcher**, then click **Save changes**.
4. Navigate to **Deploy** > **Web** > **Experience on a Website**.
5. Click on the higlighted icon and select **Change language**.
6. Select your preferred language and click **Done**.
* The chat widget language will change based on the selected language.
## Automatic RTL text alignment for Arabic
The chat widget automatically renders Arabic message bubbles in right-to-left (RTL) layout. This works for both bot/agent messages and user messages, and requires no configuration on your part.
**How it works:**
- When a message is received or sent, the widget inspects the text for Arabic script characters.
- If Arabic script is detected, the message bubble switches to RTL layout: text is right-aligned and reads from right to left.
- All inline formatting (bold, italic, links) within the bubble respects the RTL direction.
- Messages in other languages continue to display in the default LTR layout.
- Each message is evaluated independently, so mixed-language conversations align correctly without any extra setup.
:::note
RTL detection is based on the **content** of each individual message, not the bot's configured language. A bot configured in English will still render an Arabic reply in RTL.
:::
**Example:**
| Message | Direction applied |
|---------|-------------------|
| `Hello, how can I help?` | Left-to-right (LTR) |
| `شكرًا لاختيارك اللغة. كيف يمكنني مساعدتك؟` | Right-to-left (RTL) |
| User types in Arabic | Right-to-left (RTL) |
---
## Chat widget notifications
The chat widget can notify users when they receive a new message. The following are the chat widget notifications:
1. **Notification badge** - The widget displays a notification badge on top of the bot icon when a bot is in a minimized state.
2. **Favicon and title text** - When a user is on a different page or screen, the widget displays a favicon with a text message.
3. **Message sounds** - The chat widget notifies its users with a message sound when there are new messages from the bot or agents.
Chat widget notifications are supported for desktop icon styles such as circle, square, and bar. It is also supported for custom icons uploaded on the yellow platform. It is also supported for custom icons uploaded on the yellow platform.
:::note
* If there are more than nine new messages, a plus sign is displayed on the notification badge. When you click on the bot icon, you can view further messages.
:::
#### Limitations of chat widget notifications
The following are the limitations of chat widget notifications:
* Notification badges are not supported for custom icons set up on the host site, as the size details are not passed on to Yellow.
* Notification badges are not supported for mobile SDKs and PWAs as they do not have a bot icon.
* The colour of the notification badge cannot be changed at the bot level. It will remain red as per the industry standard.
## Enable chat widget notifications
To enable chat widget notifications, follow these steps:
1. On the left navigation bar, click **Extensions**.
2. Click on **Chat widget**.
3. Navigate to the **Settings** tab and expand **Notifications** drop-down.
4. Enable the **Unread message(s) badge**, **Unread notification in browser tab**, and **Message sound**, then click **Save changes**.
5. Navigate to **Deploy** > **Web** > **Experience on a Website**.
6. If there are new messages, you will see the notification in the Favicon when you are on a different tab, as shown below.
* When a bot is in a minimized state, a notification badge is displayed on top of the bot icon.
* The notification button is displayed on the header of the chat widget when Message sound option is enabled. It is turned off by default.
:::note
If there are multiple messages in a single step, you will hear the notification sound only once.
:::
---
## Chat widget
Chat widget or Web widget is an AI-agent that you can embed on a website to interact with your website users in real-time. It appears as a small chat box or window that pops up on a website or application.
Chat widget can be used to answer product queries, troubleshoot customer issues related to product features, and get quick feedback on website usability and customer service.
The **Chat widget** can be used in the following ways:
* **Automated customer service**: Used to provide 24/7 automatic customer service by offering instant assistance for customer queries, booking appointments directly from a website, and so on.
* **Promotion and marketing:** It can be used to promote and advertise your products and services to the website's visitors. It also provides product recommendations based on a user’s browsing history.
* **Shopping assistance**: It helps website users find their products and services quickly.
* **Collecting feedback**: It can be used to collect reviews and ratings for your products and services from website visitors that can be used to improve customer satisfaction.
In our platform, the Chat widget allows users to customize design of the widget, preview, and deploy it as per their custom requirements. Click [here](https://docs.yellow.ai/docs/platform_concepts/channelConfiguration/web-widget) to know more.
To match any use case, the Chat widget can be customised in various ways using [Functions](https://docs.yellow.ai/docs/platform_concepts/channelConfiguration/function-widgets) and [Events](https://docs.yellow.ai/docs/platform_concepts/channelConfiguration/event-widget).
You can retrieve the data of the user who is using the Chat widget by using the [Payload](https://docs.yellow.ai/docs/platform_concepts/channelConfiguration/chat-widget-payload).
---
## Chat widget payload
A payload is used to pass the information to the bot.
Consider that you have a requirement to pass the data of the user who is using the chat widget. In such cases, you can use payload to pass data from your website to the bot. For example, payload passes the data such as account IDs, customer identifiers like names, email addresses, and phone numbers, or other metadata associated with a user from your website to the bot.
In the payload, you need to create a string that is a key-value pair consisting of data and its value (in lower case). The data must have string-to-string key-value pairs. Payload is passed in JSON format. An error is displayed when data other than key-value is passed in the JSON code.
:::note **payload security**
Payload is securely passed in HTTPS post request to secure the information passed in it.
:::
In this article, you will learn:
* [How to pass the payload data](#1-pass-values-from-the-web-client-to-the-bot)
## 1. Pass values from the web client to the bot
To pass values from your parent interface to the bot, you can make use of **payload data**, which needs to be configured in the bot script and init function.
### 1.1 Pass payload data via bot script
To pass the payload data via script, paste the bot script at the end of the `` tag
**Following is a sample bot script:**
```c
```
Add the payload data in the following bot script:
```c
```
The bot is initilized when the page loads. Once the bot loads, you can assign these values to variables using [Variables node](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes#variables).
Variable format is ```{{{profile.payload.Your_Field_Name}}```
### 1.2 Pass payload data via init function
You can also pass the payload data via the init function. If you want to reinitialize the bot with a new payload, you can use the below script:
```c
window.YellowMessengerPlugin.init({
payload: {
email: 'ted.lasso@yellow.ai',
member_id: '1231basd' // you can pass any info you want to be associated with the user based on your use case here. Note that this can be read by the bot using the {{profile.payload.member_id}} variable.
}
});
```
---
## Chat widget Text formatter
You can style the text on the Chat Widget as per your needs using the Markdown syntax to enhance the user experience. With the Markdown syntax, you can emphasize important information and capture the reader's attention within specific parts of the conversation.
**Watch the video on how to format the text in the bot conversation:**
Use the following syntax for styling the text in the bot conversation:
* **Bold**: Use asterisks to enclose text when you want to emphasize or highlight its importance. (`*text*`).
* **Strikethrough**: Achieve a strikethrough effect by enclosing the text with tildes. (`~text~`)
* **Italic**: Italicize specific words or phrases by using underscores. (`_text_`)
* **Bulleted Lis**t: Organize information in a structured manner by starting a statement with a hyphen and a space. (`- text`)
* **Highlight text**: To highlight specific text, enclose it with colons. (`:text:`)
Input | ouput
-----|-------
`*Welocme to web widget world*` | **Welcome to web widget world**
`1.(press space) This is a normal list` | 1. This is a normal list.
`-(press space) This is a bullet list` | • This is a bullet list
`-Why is this text cut?:p~`| ~~Why is this text cut?:p~~
`_This is italic_` | *This is italic*
`Oh i'm in the <>` | Oh i'm in the highlight
## Enable text formatting
To enable text formatting, follow these steps:
1. On the left navigation bar, click **Extensions**.
2. Click on **Chat widget**.
3. Navigate to the **Settings** tab > **Configure settings** and enable **Text formatting**.
4. Click **Save changes**.
5. Navigate to **Automation**, select the required flow, and in the respective node format the text.
6. Navigate to **Channels** > **Chat widget** > **Deploy** > **Web** > **Experience on a Website**.
* You can view the formatted text in the widget.
---
## Install chrome extension
The Chrome extension allows you to paste the script of your bot on any webpage to test your development bot's payload and authentication locally on your device without having to publish changes to Live.
After customising your chatbot, you can preview it and add it to your website.
## 1. Add chatbot to website
Follow these steps to add a Chrome extension and to preview your customised chatbot on a website:
1. Install the Chrome extension using this [link](https://chrome.google.com/webstore/detail/yellowai-web-widget-launc/hlajdopahpkoakfedombhdpomlpmafbb).
2. Copy the chat widget code as explained [here](https://docs.yellow.ai/docs/platform_concepts/channelConfiguration/web-widget#deploy-chat-widget).
3. Open the extension in your Chrome browser.
4. In the first input box, enter the entire website URL. The chat widget will appear on the website based on the URL that you have entered here.
5. In the second input field, paste the chat widget script you copied in step 2 and click **Launch Widget**.
6. Open the website URL that you have entered in the first input box to view your chatbot.
---
## Content Security Policy
Content Security Policy (CSP) is a security standard implemented by web browsers to provide an additional layer of security for your website. It functions as a gatekeeper, determining who or what is permitted to access your website and significantly reduces the risk of cross-site scripting (XSS) attacks, data breaches, and other malicious activities.
CSP allows website administrators to specify the allowable resources, such as scripts, stylesheets, and images, that can be loaded by web pages. By defining these rules, you can prevent unauthorized individuals or malicious content.
Consider a scenario where you have a website that allows user-generated content, like a forum or a comment section. In the absence of CSP, an attacker could inject malicious code into user comments or forum posts, posing a serious threat to user data and potentially spreading malware. However, by implementing CSP, you can specify that only scripts from trusted sources are allowed to run on your website, effectively blocking any unauthorized code from executing.
## Add CSP to your website
To implement Content Security Policy (CSP) on your website, configure the Content-Security-Policy header in your server's response. This header allows you to define the rules for your website's content security policy. You can specify directives such as `default-src`, `script-src`, `style-src`, `img-src`, `media-src`, and so on, to control the sources from which different types of content can be loaded.
For instance:
* To allow only the resources to be loaded from the same origin, or specify specific domains or trusted sources for different types of content, set `default-src 'self'`.
* To specify a URL where violation reports should be sent, use the `report-uri` directive.
## Add rules to your website
You can implement these rules on your website using the following methods:
1. **Using Meta tag in Static HTML Webpage**
This meta tag all resources from the current domain along with all subdomains of yellow.ai.
```javascript
;
```
2. **Using Headers in Server Configuration**
```javascript
add_header Content-Security-Policy-Report-Only "default-src 'none'; form-action 'none'; frame-ancestors 'none';"
```
If you find server configurations challenging, reach out to your infrastructure team for assistance. Alternatively, you can refer to this [link](https://mattferderer.com/how-to-add-a-header) for better understanding.
## Types of resources
You can also specify what type of resources you would like to load from certain origins. For example, let’s say you want to allow loading videos only from YouTube, images from Cloudinary, and fonts from Google fonts, and the rest of the other content only from your website. You can create a rule like this.
```javascript
add_header Content-Security-Policy-Report-Only "default-src 'self'; media-src https://youtube.com; img-src: https://*.cloudinary.com; font-src https://*.google.com;"
```
or
```javascript
;
```
In the above example:
* `default-src 'self'`: Allows resources (images, scripts, styles) to be loaded only from the same origin.
* `media-src 'self' https://www.youtube.com`: Allows media resources, such as videos, from the same origin and YouTube.
* `img-src 'self' https://res.cloudinary.com`: Allows images from the same origin and Cloudinary.
* `font-src 'self' https://fonts.gstatic.com`: Allows fonts to be loaded from both the same origin and the specified Google Fonts origin.
Now that you have got a basic idea of what CSP is and how to configure on your website. Let’s see how to add a CSP to ensure Yellow.ai chat widget performs as expected.
## Configure CSP for Yellow.ai Chat widget
Yellow.ai's chat widget:
- Makes a socket connection with wss://cloud.yellow.ai/websocket,
- Fetches assets from https://cdn.yellowmessenger.com,
- Tracks how the widget is used from `blob://`. (a web-worker that is created on the parent website’s domain).
- Makes API requests to `https://*.yellow.ai`.
So you need to create the rules as follows:
1. You can add all the resources to the `default-src`.
```javascript
add_header Content-Security-Policy-Report-Only "default-src 'self' https://*.yellow.ai https://*.yellowmessenger.com wss://*.yellow.ai blob://*.your_website.com;"
```
or
```html
;
```
2. Or, you can specify exactly what type of resources that you would like to allow from our domains.
```javascript
add_header Content-Security-Policy-Report-Only "default-src 'self' 'unsafe-inline'; connect-src wss://*.yellow.ai https://*.yellow.ai; script-src https://*.yellowmessenger.com; style-src https://*.yellowmessenger.com; worker-src blob://*.your_website.com;"
```
--------- or ---------
```html
;
```
:::note
If you explicitly specify a rule to allow a type of resource only from these websites and Yellow’s resource is not from one of those sources, the resource will be rejected.
For instance, specifying `font-src 'self';` restricts font loading from Yellow's CDN. However, omitting this rule would prompt the browser to check the parent rule instead (default-src).
:::
---
## Set up custom bot icon
A custom bot icon is displayed in the corner of the website. You have the flexibility to customize this icon according to your branding and visual style. You can have a custom icon for your chat widget.
There are two ways to set the custom bot icon:
1. [Set a custom icon through the Yellow.ai platform](#set-custom-bot-icon-via-platform)
2. [Host custom icon on your website](#host-custom-icon-on-your-website)
## Set custom bot icon via platform
To set the custom bot icon, follow these steps:
1. On the left navigation bar, click **Extensions**.
2. Click on **Chat widget**.
3. Navigate to **Bot icon**, under *Icon shape*, select the **Upload custom icon** option.
4. Click **Add icon** to upload the custom icon.
5. Choose the icon from your local system and click **Open** to upload the icon. You can view the custom icon on the *Preview* screen.
:::note
You can choose any animation for the icon if needed.
:::
## Host custom icon on your website
To display a custom bot icon on your website, you should hide the default bot icon and use the bot function to load the bot when users click on the icon. For more information on the process, click [here](https://docs.yellow.ai/docs/platform_concepts/channelConfiguration/function-widgets#hide-the-bot-by-default).
---
## Embed chat widget on SharePoint
This guide outlines the process of embedding the Yellow.ai chat widget into your Microsoft SharePoint site using [SharePoint Framework](https://github.com/pnp/sp-dev-fx-webparts/tree/main/samples/react-script-editor) (SPFX) extensions.
To proceed, ensure you have admin access to SharePoint. For more detailed information on SharePoint, click [here](https://support.microsoft.com/en-us/sharepoint).
## Add your chat widget to SharePoint site
To add your chat widget to SharePoint site, you need to perform the following steps:
1. [Add the Extension](#activate-the-extension-on-your-sharepoint-site)
2. Upload the extension to SharePoint admin center
3. Activate the extension on your SharePoint site
4. Embed the chat widget
### Step 1: Choose your extension and package it
Before proceeding, determine whether to utilize an existing extension or develop a new one, and ensure proper packaging.
1. **Select your extension**: Decide whether to use an existing extension or create a new one. You can explore various extensions in the Microsoft community-maintained GitHub repository. In this scenario, a `script editor web part for modern pages` extension is used.
:::note
If you want to develop your own extension, refer to the available tutorials and guides.
:::
2. **Packaging instructions**: Follow the packaging instructions provided on the web part's GitHub page. For additional help, refer to the [Deploy your client-side web part to a SharePoint page](https://learn.microsoft.com/en-us/sharepoint/dev/spfx/web-parts/get-started/serve-your-web-part-in-a-sharepoint-page).
3. You can also use our existing [package](https://drive.google.com/file/d/1-VZdG7pinHCeBv2xJkHWWMmsXf5i8_Df/view?usp=sharing).
Once the packaging process is finished, you will receive a file with the `.sppkg` extension. This file contains your packaged extension, ready for deployment.
### Step 2: Upload the extension to the SharePoint admin center
Once you have packaged the extension, follow these instructions to upload it to your SharePoint site, as explained here:
1. Access your SharePoint admin center by appending `/admin` to your SharePoint site URL.
2. Navigate to the **Manage apps** page, where you can upload packages with the `.sppkg` extension. Ensure that the state of the package is set to **Enabled**.
* This will upload your extension to your SharePoint site. For assistance on uploading the package, refer to [Deploy your client-side web part to a SharePoint page](https://learn.microsoft.com/en-us/sharepoint/dev/spfx/web-parts/get-started/serve-your-web-part-in-a-sharepoint-page).
### Activate the extension on your SharePoint site
To enable the extension at the site level, follow these steps:
1. Navigate to the **Settings** on your SharePoint site.
2. Click **Settings** icon, then select **Add an app**.
3. Choose your app from the list, and click **Add**.
4. Go to **My apps** page to view the package that you have previously added under *Added apps*.
### Embed the Web Widget
Once your extension is activated, you can embed the chat widget on your page. Follow these steps:
1. Open the SharePoint page where you want to embed the chat Widget.
2. Click **Edit** to enter edit mode.
3. Navigate to the web section at the top of the page, then select the extension you added.
4. Click **Edit markup**, and then select **Edit HTML Code**.
5. In the script editor, add your widget script.
Here is the sample widget script:
```javascript
```
The chat widget is integrated into your SharePoint page:
---
## Deploy WhatsApp bot on website and Mobile application
Let's say that you have built a bot for the WhatsApp channel and now want to deploy it on your website or mobile application using a chat widget. This document will provide you with step-by-step instructions on how to port your WhatsApp bot to your website or mobile application using a chat widget.
:::note
* You can use the V2 widget using the bot script from the cloud.yellow.ai platform even if the bot code is in the app platform.
* You can use Mobile SDKs for deploying WhatsApp bot on [iOS](https://docs.yellow.ai/docs/platform_concepts/mobile/chatbot/ios) and [Android](https://docs.yellow.ai/docs/platform_concepts/mobile/chatbot/android) apps.
:::
To deploy an existing WhatsApp bot on a website or mobile application, follow these steps:
1. To create a separate flow using the WhatsApp specific components such as WhatsApp quick reply and list card.
2. Use the provided code snippet in the [function](https://docs.yellow.ai/docs/platform_concepts/studio/build/code) while creating the flows based on your use case:
```js
if (app.source == "whatsapp") {
// actions or message list which you want to display
}
if(app.source == "yellowmessenger"){
// actions or the quick replies which you want to display.
}
```
3. On the overview page, select your bot and enter your respective bot ID in the browser URL.
4. Navigate to **Channels** > **Chat widget** > **Deploy** > Copy the bot script provided.
5. Paste the bot script on your website where you want the bot to appear. For more information, click [here](https://docs.yellow.ai/docs/platform_concepts/channelConfiguration/web-widget#24-deploy-chat-widget).
* You can also configure the appearance of your bot on the cloud platform. For more information, click [here](https://docs.yellow.ai/docs/platform_concepts/channelConfiguration/web-widget).
---
## Domain whitelisting for Chat widget
Domain whitelisting allows you to secure your chatbot and ensures chatbot acces only in authorized domains. It prevents unauthorized users from copying the script and embedding the bot on their websites and Mobile SDK apps (Android and iOS apps).
Yellow.ai allows businesses to whitelist domain(s) where you want to deploy the chatbot.
:::note
* When a domain (example: yellow.ai) is whitelisted, all its subdomains (example: cloud.yellow.ai, live.yellow.ai) will also be whitelisted by default.
* Yellow.ai and yellowmessenger.com are whitelisted by default to allow you to preview your chatbot seamlessly.
:::
## Whitelist domain(s) to deploy chat widget
To whitelist a domain to deploy chat widget, follow these steps:
1. On the left navigation bar, click **Extensions**.
2. Click on **Chat widget**.
3. Navigate to the **Secure bot** tab and expand the drop-down corresponding to **Web**.
4. Enter the domain that you want to whitelist, then click **+ Add**. You can also add multiple domains based on your requirements.
:::note
- If none of the domains are whitelisted, the chatbot will load on all domains where the script is deployed
- If one or more domains are whitelisted, the chatbot will load only on whitelisted domains.
:::
* The domain will be successfully whitelisted.
5. If your domain is not whitelisted, a red tick mark next to your domain will be displayed. Click **Whitelist Domain** to load your bot.
6. A pop-up is displayed with a confirmation message, click **+ Whitelist domain** to whitelist your domain.
* This will whitelist your domain.
7. To test your chatbot locally, you need to enable **Allow localhost**. Note that, you need to disable it after deployment.
### Remove whitelisted domains
To remove whitelisted domains, follow these steps:
1. To remove the added domain, click **Remove domain** icon.
2. A pop-up is displayed with a confirmation message, click **Remove**.
## Whitelist Mobile apps
The platform supports whitelisting for bots deployed using all SDK frameworks, including Android, iOS, React Native, Cordova, and Flutter. By default, the bot will load on any app where the SDK is integrated. If you choose to whitelist one or more apps, the bot will exclusively load in the whitelisted app.
To whitelist specific apps, follow these steps:
1. Navigate to the **Secure bot** tab and expand the drop-down corresponding to **App**.
3. Enter the **App ID** of your app and click **+ Add**. You can also add multiple app IDs based on your requirements.
* This will whitelist your app.
### Remove whitelisted Mobile apps
To remove whitelisted apps, follow these steps:
1. To remove the added app, click **Remove domain** icon.
2. A pop-up is displayed with a confirmation message, click **Confirm**.
* This will remove the whitelisted app.
---
## Download chat transcript
You can allow your bot users to download chat transcripts in a plain text (.txt) format directly from the chat widget. This facilitates bot users to access their complete conversation history with the bot.
The downloaded chat transcripts include information such as the bot's name, user's name, timestamp (displaying the full date and time), and the messages exchanged between the bot, agent, and user.
Following are the important points for downloading chat transcripts:
* This is supported for web bots, PWA, and SDK.
* It supports multiple languages.
* Available only for the ongoing session (within 24 hours of chat initiation).
## Enable download transcript
To enable download transcript, follow these steps:
1. On the left navigation bar, click **Extensions**.
2. Click on **Chat widget**.
3. Navigate to the **Settings** tab, expand **Chat history** drop-down to enable **Download transcript**, then click **Save changes**.
4. Navigate to **Deploy** > **Web** > **Experience on a Website**.
5. Click the below-highlighted option, then select **Download transcript**.
---
## Email channel configuration
Email is a communication channel through which the organization can interact with users and vice versa. It allows the organization to send campaigns, receive tickets, address support requests, gather feedback, respond to inquiries, or engage in general communication.
When users send an email to the designated email address, the support agents from the organisation will respond to the email accordingly. You can use email for two-way communication to chat with your users. For example, support@organization.com or sales@organization.com.
The following are the different protocols for sending emails:
1. SMTP
2. HTTP-based Email API
3. Connect with Microsoft (OAuth)
### Email SMTP
Simple Mail Transfer Protocol (SMTP) is a simple mechanism to send or receive emails from or to your mail server. Traditionally, the one-off emails that we send from our mailbox to another are generated by SMTP.
:::note
Use SMTP configuration when the purpose is to send 1:1 transactional/update email notifications through our [Notifications API](https://docs.yellow.ai/docs/platform_concepts/engagement/outbound/notification-engine) or [Workflow](https://docs.yellow.ai/docs/platform_concepts/engagement/flows_campaign) campaign, and not usually recommended for bulk promotional ones.
:::
### Web-based Email API
A web-based Email API is a mechanism to exchange emails via HTTP (Hypertext Transfer Protocol). It allows you to access the functionality of the email services such as sending and receiving emails, managing contacts and mailboxes, and performing other email-related tasks, within the applications or systems.
### Difference between SMTP and Email API
|SMTP | Email API |
|--|--|
| SMTP is a protocol used to transfer emails between servers. The brand’s own SMTP can be used for sending transactional, support, workflow-driven, or one-off emails. | Email API is a set of tools and functions provided by an email service provider to allow you to programmatically interact with their email services. |
|This mechanism is not recommended for sending bulk or promotional email campaigns.| This mechanism can be chosen when the use case is to send bulk emails for promotional goals. |
## Add sender email account
You can add sender email acount either by configuring the SMTP of the brand’s professional sender email ID or by adding the web-based email API key to the platform. Upon successful configuration, the platform can send emails from the associated Email ID.
### Set up SMTP-based email account (Basic)
This setup allows our platform to send emails on behalf of the email domain.
To set up SMTP server on the yellow.ai platform, follow these steps:
1. On the left navigation bar, click **Extensions**.
2. Click **Channels** > **Messaging** > **Email**.
3. Click **Add email**
4. In the *Add Email* section, select **Basic** to add the details of the Email sender.
Enter the following details:
* **Configuration objective**: Select the purpose of the current email account - Campaigns or Support ticketing. You can select both if needed.
* **Campaigns** - You can choose this option to send the campaigns such as promotions, newsletters and updates, event invitations, and so on. You need to create a [email template](https://docs.yellow.ai/docs/platform_concepts/engagement/outbound/templates/email-template) to exceute a campaign. After creating a template, you need create a email campaign. For more information, click [here](https://docs.yellow.ai/docs/platform_concepts/engagement/outbound/outbound-campaigns/run-campaign#32-email-campaign).
* **Support ticketing** - You can choose this option to raise your queries so that agent can track inquiries effectively. Each email received from a user is considered as a ticket. This helps support teams manage and prioritize incoming requests. For more information, click [here](https://docs.yellow.ai/docs/platform_concepts/inbox/tickets/tickets_intro).
* **Email**: Enter the email address (sender ID) that you want to associate with the account. For example, support@organization.com.
* **Server**: Enter the host URL. The value will be unique for each mail server. For example, it will be `smtp.gmail.com` for the Gmail server and `smtp.office365.com` for the Outlook server. In some cases, like a private server, the value will be the IP address of the SMTP connector service.
* **Username**: Enter the same email address that you entered in the Email field. For shared accounts such as Microsoft, these could be different.
* **Password**: Enter the app password of the specified email address. To know how to generate and use an app password for each server, see [Google](https://support.google.com/accounts/answer/185833?hl=en) and [Microsoft](https://support.microsoft.com/en-us/account-billing/using-app-passwords-with-apps-that-don-t-support-two-step-verification-5896ed9b-4263-e681-128a-a6f2979a7944).
:::note
* You should enter the same input for the email ID and username.
* Some email servers like Gmail offers [safer alternatives](https://support.google.com/mail/answer/185833?hl=en) to expose the password. You can generate it and provide it while configuring SMTP.
* For more details on SMTP, reach out to your IT team.
:::
* **Port**: Select port **465** for Gmail and port **587** for Outlook when setting up the SMTP connection.
* **Security type**: Choose **SSL** for Outlook or **TLS** for Gmail when selecting the appropriate security type for the SMTP connection.
* Click **Save**.
* Once the email account details are saved, forwarding address will be displayed.
Similarly, you can add multiple email accounts and choose your preferred sender ID when configuring an outbound campaign.
#### **Set forwarding address**
The forwarding address generated within the platform must be added to your email server's setup, be it Gmail, Outlook, or another email server.
###### Prerequisite
* Copy the forwarding address from the Email channel page
To configure a forwarding address, follow these steps:
1. Go to the [Gmail](https://mail.google.com/) account.
:::note
You can only forward messages to a single Gmail address, not an email group or alias.
:::
2. Click on **Settings** (top right) > **See all settings**.
3. Click **Forwarding and POP/IMAP** tab.
4. In the "Forwarding" section, click **Add a forwarding address**.
5. Paste the forwarding address that you have copied from the Email channel page and click **Next**.
6. Click **Proceed** > **Ok**.
7. A confirmation link will be sent to the **Bot Messages** section of the Inbox module. Click the below highlighted link.
8. Click **Confirm**.
* Once confirmed, the email ID you have added will forward emails to your designated forwarding address.
#### Add email alias account
You can add email alias account, if already main account configured in chatbot for alias.
To add an email alias account, follow these steps:
1. On the left navigation bar, click **Extensions**.
2. Click **Channels** > **Messaging** > **Email**.
3. Click **Add email**
4. Choose the account type as **Configure account**.
5. In the *Add Email* section, enter the following details:
* In the email field, enter the email address of the alias account.
* In the username field, enter the email address of the main account.
In the password field, enter the app password associated with the main account and click **Save**.
### Set up SMTP-based email account (JSON)
You can also configure SMTP using the JSON code.
To configure an SMTP using JSON, follow these steps:
1. Click **Channels** > **Messaging** > **Email**.
2. Click **Add email**
3. Select **Configure account**.
4. In the *Add email* section, select **Advanced** to add the SMTP details of the email address in the JSON code for which you want to send emails.
5. Copy the below JSON code, paste it in the *Advanced configuration* section, and click **Save**.
```js
{
"serviceType": [
"supportTicketing"
],
"address": "customerservice@shopping.id",
"outboundConfig": {
"server": "outlook.office365.com",
"port": 587,
"username": "customerservice@shopping.id",
"name": "Customer Service Shopping",
"password": "abc",
"securityType": "SSL",
"useAdvanceConfiguration": true,
"advanceConfiguration": {
"service": "Outlook365",
"auth": {
"user": "customerservice@shopping.id",
"pass": "abc"
}
}
}
}
```
:::note
* To send mail on behalf of the client, the client should enable SMTP authentication.
* In cases where clients have disabled SMTP auth for security reasons, they can whitelist Yellow.ai’s IP and allow emails from that IP.
* For Yellow.ai to receive emails from the customers of the client, the client needs to configure a unique forwarding address provided by Yellow.ai after configuring an email on the Channels page.
:::
### Get your Outlook SMTP
To get Outlook SMTP, follow these steps in Outlook:
1. Navigate to the **File** menu.
2. Click Info. Go to the **Account Settings** page.
3. On the Yellow.ai platform, look for the email address that you want to configure.
4. Search for the **Outgoing server field**.
* You will see the SMTP that you want.
### Get your Gmail SMTP
For emails to be sent from smtp.gmail.com, make sure you have followed these 2 steps:
1. Enable 2-Step Verification in your Google account.
2. Go to https://security.google.com/settings/security/apppasswords.
a. Click **Select app** and choose Other (custom name) from the dropdown.
b. Click **Generate**.
c. You will receive a 16-digit code, this code should be used as a password in email configuration, and the user remains as your email.
### Web-based email account (API)
Reach out to the [yellow.ai team](mailto:vishnu@yellow.ai) for setting up an email account. The process will cover domain/subdomain authentication and dedicated IP address procurement, among others.
### Setup Email channel with OAuth
You can configure your email account with Microsoft OAuth to establish a secure and seamless connection between your email service and the AI agent. This allows the agent to send and receive emails without storing passwords.
:::tip
If you use **Microsoft 365** with **your own Azure app**, **OAuth client credentials**, and optionally **inbound mail without forwarding** (Microsoft Graph webhooks), follow the dedicated guide: [Microsoft 365 direct email connector](#microsoft-365-direct-email-connector) (start from [Overview](#overview-m365-direct-connector) or jump to [How to configure on Yellow.ai](#how-to-configure-on-yellowai-m365-email)).
:::
#### Generate credentials on azure portal
1. Log in to the [Microsoft Azure](https://portal.azure.com/) portal.
2. Go to **App registrations**.
3. Select your registered application.
4. In your registered application, copy **Client ID** and **Tenant ID**.
5. Go to **Certificates & secrets** > **Client secrets** > copy the **Client secret value**.
#### **Configure Email channel with OAuth**
To connect an email account with OAuth, follow these steps:
1. On the left navigation bar, click **Extensions**.
2. Click **Channels** > **Messaging** > **Email**.
3. Click **Add email**
4. Select **Connect with Microsoft** as the account type.
5. In the *Add Email* section, enter the following details:
* **Configuration objective**: Select the purpose of the current email account - Campaigns or Support ticketing. You can select both if needed.
* **Email ID**: Enter the email address of the alias account.
* **Client ID**: Paste the Client ID copied from [step 5 of Generate credentials on azure portal](#generate-credentials-on-azure-portal)
* **Client secret**: Enter the copied secret value generated in Azure to authenticate your application.
* **Tenant ID**: Paste the Tenant ID copied from [step 5 of Generate credentials on azure portal](#generate-credentials-on-azure-portal) where your application is registered.
6. Click **Connect**.
### Microsoft 365 direct email connector
#### Overview {#overview-m365-direct-connector}
##### What is this feature?
This feature lets your Yellow.ai bot connect **directly** to your organization’s **Microsoft 365 / Exchange Online** mail through **Microsoft Graph**. The bot can **send** mail and, when you turn on the right option, **receive** support mail in near real time **without** relying on classic mailbox forwarding into Yellow.ai.
Yellow.ai authenticates using the **OAuth 2.0 client credentials** flow (also called **app-only** or **server-to-server**). That means **we do not store user passwords** for this connection — only the Azure **client ID**, **tenant ID**, and **client secret** you provide, which your IT team controls and rotates in Azure.
##### Why use this instead of traditional email forwarding?
| Benefit | What it means for you |
| --- | --- |
| **Simpler mail routing** | You connect at the **source** (Microsoft 365). With webhooks enabled, you **do not** maintain a separate rule that forwards every inbound mail to a Yellow.ai-generated address. |
| **Fast, reliable inbound** | New mail is signaled with **secure Graph webhooks** (change notifications). Yellow.ai then **pulls the full message** from Microsoft. This is **not** “slow polling” of the mailbox on a long timer. |
| **Enterprise-friendly auth** | **Client credentials** are standard for integrations owned by the organization. Access is governed in **Azure** and **Microsoft 365**, alongside your other app registrations. |
##### How you receive mail:
When you add the channel in Yellow.ai, **Enable webhook** decides **how inbound mail reaches the bot**:
| **Enable webhook** | What happens for **incoming** mail | When to choose it |
| --- | --- | --- |
| **Enable** | Microsoft notifies Yellow.ai when a **new message is created in that mailbox’s Inbox**. Yellow.ai **downloads** the message from Graph. **No forwarding rule** to Yellow.ai is required for ingestion. | Default recommendation for “direct connector” behaviour: cleaner routing. |
| **Disable** | OAuth still backs the connection for sending as configured, but **incoming** mail follows the **Yellow.ai forwarding address** model, same idea as [Set forwarding address](#set-forwarding-address). | If Graph subscription creation fails, your security team prefers forwarding, or you are rolling out in phases. |
:::note
**Scope:** This connector is for **Microsoft 365 / Exchange Online**. It does **not** apply to **Gmail / Google Workspace** or arbitrary IMAP hosts — use **SMTP** or another supported method for those.
:::
---
#### Prerequisites {#prerequisites-m365-direct-connector}
Before anyone opens Yellow.ai, confirm the following:
| Requirement | Details |
| --- | --- |
| **Microsoft 365 / Exchange Online** | The mailbox you connect must live in **Microsoft 365** (Exchange Online). This path is **not** for Gmail/Google Workspace. |
| **IT / admin access in Azure** | Someone who can work in **Microsoft Entra ID** (Azure AD) — typically a **Global Administrator** or an admin who can **register applications** and grant **admin consent** for **Microsoft Graph application permissions**. |
| **Mailbox to automate** | Often a **shared or dedicated** address such as `support@company.com` so support traffic and credentials are isolated from individual users’ mailboxes. |
---
#### Setup guide for Microsoft 365 {#setup-guide-for-microsoft-365}
Complete these steps in the **[Microsoft Azure Portal](https://portal.azure.com/)**. When you finish, you will have **Application (client) ID**, **Directory (tenant) ID**, and a **Client secret value** to paste into Yellow.ai in [Configuration in Yellow.ai](#how-to-configure-on-yellowai-m365-email).
##### Step 1: Register the application
1. Sign in to the **Microsoft Azure Portal**.
2. Search for and open **App registrations** (under **Microsoft Entra ID** / **Azure Active Directory**).
3. Click **+ New registration**.
4. Fill in the form:
* **Name** — for example `YellowAI-Email-Connector` (any clear name your IT team recognizes).
* **Supported account types** — choose **Accounts in this organizational directory only (Single tenant)**. For an internal support mailbox, **single tenant** is usually the strictest and clearest option.
* **Redirect URI** — leave **blank** for this flow (client credentials do not use a browser redirect the way some sign-in flows do).
5. Click **Register**.
##### Step 2: Copy IDs and generate a client secret
1. Stay on the app’s **Overview** page. Copy **Application (client) ID** and **Directory (tenant) ID** — you will enter them in Yellow.ai as **Client ID** and **Tenant ID**.
2. In the left menu, open **Certificates & secrets**.
3. Under **Client secrets**, click **+ New client secret**.
4. Set **Description** (for example `YellowAI-Secret`) and **Expires** (for example **12 months**, or whatever your security policy requires). Click **Add**.
:::danger
**Copy the secret *Value* immediately.** After you leave the page, you **cannot** read that value again. If you lose it, create a **new** secret in Azure and update Yellow.ai.
:::
##### Step 3: Grant Microsoft Graph *application* permissions
Yellow.ai uses **application** permissions (app acts on its own), **not** delegated permissions (sign in as a user).
1. In the left menu, click **API permissions** → **+ Add a permission**.
2. Click **Microsoft Graph**.
3. Choose **Application permissions** (**not** Delegated).
4. Add these three permissions (use the search box in the portal):
* **Mail.Read** — read mail so the bot can **ingest** inbound messages.
* **Mail.ReadWrite** — update mail (for example **read state**, moves, or other operations your product uses for support workflows).
* **Mail.Send** — **send** replies and outbound mail as the configured mailbox.
5. Click **Add permissions** to save the list.
:::warning
**Admin consent is mandatory.** You will see a consent warning until an admin approves. Click **Grant admin consent for [Your organization]** and confirm.
**Success check:** Every permission row should show **Granted for [Your organization]** with a **green** status (checkmark). If any row is **Not granted**, inbound or outbound Graph calls can fail until consent is fixed.
:::
---
#### Configuration in Yellow.ai {#how-to-configure-on-yellowai-m365-email}
Do this **after** Azure steps are complete and you have copied **Application (client) ID**, **Directory (tenant) ID**, and **Client secret value**.
##### Open the Email channel (Microsoft path)
1. Log in to **Yellow.ai** and open the **bot** that should own this mailbox.
2. Go to **Extensions** → **Channels** → search for **Email** channel.
3. Click **Add email**.
4. Under **Choose how you want to connect account**, select **Connect with Microsoft**.
5. On **Add email** → **Account details**, enter:
| In Azure (source) | In Yellow.ai (field name on the form) |
| --- | --- |
| **Application (client) ID** on the app **Overview** | **Client ID** |
| **Directory (tenant) ID** on the app **Overview** | **Tenant ID** |
| **Value** of the client secret from Step 2 | **Client Secret** |
| The mailbox the bot should use (for example `support@company.com`) | **Email Id** (this is your **target mailbox** on Graph) |
Also set:
* **Configuration objective** — same meaning as elsewhere in this doc ([SMTP basic setup](#set-up-smtp-based-email-account-basic)): **Campaigns**, **Support ticketing**, or both, depending on how this mailbox is used.
* **Enable webhook** — **Enable** for **direct** inbound via Graph (no forwarding rule required). **Disable** if you intentionally want to use the **Yellow.ai forwarding address** for inbound instead ([Set forwarding address](#set-forwarding-address)).
6. Click **Connect**.
---
#### Security & FAQ {#security-and-admin-faq-direct-connector}
**Q: Does granting “Application permissions” mean the app can read every mailbox in the tenant?**
**A:** In many tenants, **application** mail permissions are **broad by default** unless you add extra controls. That is why admin consent and change management matter. If you must **limit** the app to **specific mailboxes** (for example only `support@company.com`), your Exchange Online team can use **application access policies**. See Microsoft’s guide: [Limiting application permissions to specific Exchange Online mailboxes](https://learn.microsoft.com/en-us/graph/auth-limit-mailbox-access).
**Example (Exchange Online PowerShell)** — replace placeholders with values **your administrator** obtains from Entra ID / Exchange (the `-PolicyScopeGroupId` parameter expects a **mail-enabled security group** or other **allowed scope object ID**, not a raw SMTP string):
```powershell
New-ApplicationAccessPolicy `
-AppId "YOUR_APPLICATION_CLIENT_ID" `
-PolicyScopeGroupId "YOUR_SCOPE_GROUP_OR_MAILBOX_OBJECT_ID" `
-AccessRight RestrictAccess `
-Description "Restrict Yellow.ai email connector to approved mailboxes"
```
---
## Test your bot on Email
After connecting your bot to an email account, you can test your bot using the following process.
To test your bot on Email, follow these steps:
1. Go to your email account and send a mail to the customer support team. Enter the same mail address that you have configured in the STMP basic email section.
3. The ticket will be raised in the Inbox. Navigate to **Inbox** > **Tickets**.
4. The agent(customer support team) will send an email to your email address regarding your query.
## Email troubleshooting
### Troubleshooting email configuration
When configuring email, you might encounter the following issues:
* If you have entered a different email ID and username, the email channel will not be configured.
* If you have entered an invalid password, the email channel will not be configured.
To troubleshoot, follow these steps:
1. On the Email channel page, **right-click > Inspect > Network**.
2. Select the "add_config" API and click **Preview** to view the error message.
Similarly, if you have entered an invalid password, you can follow the above steps to troubleshoot.
## Generate app password for Email Tickets
Sometimes, emails from agents might not reach the end users. To solve this problem, we can use an app password. This helps make sure agents and users can communicate better.
**Prerequisites**
You'll need access to the same email account and password that's linked to the bot.
**Steps**
1. Log in to the email account linked to the bot.
2. Use the link below to make the app password: [App Password Creation Guide](https://support.google.com/accounts/answer/185833?hl=en)
3. Make the app name, then you'll get a 16-character app password.
4. Remove any spaces from the password and copy it.
5. Paste this password into the email settings.
---
## Chat widget events
Bot events are the actions that occur within a chatbot when specific actions are performed during the conversation. Events are triggered when a user clicks on button links, opens, or closes the chatbot.
You can use these events to trigger specific bot flows, run campaigns, or perform any other actions based on your requirements.
## Send event to bot
```js
// find the yellow.ai widget iframe
const ymIframe = document.getElementById('ymIframe');
// event_name should be a valid name supported by the widget.
const message = JSON.stringify({code: 'event_name', data: {...}});
// send a cross-site message using
// window.postMessage(message, targetOrigin, transfer) API.
ymIframe.contentWindow?.postMessage(message, window.location.origin);
```
## Listen to a bot event
```js
```
## Supported events
The following are some of the events supported by our chat widget:
| Event | Description |
|--------|---------------|
| bot-opened | This event occurs when a user clicks on the chat bubble to open the bot on a website. For Progressive Web App (PWA), it triggers when the bot loads. |
| bot-closed | This event is triggered when the user closes the bot on the website.|
| bot-loaded-on-page-reload | This event is triggered when the user reloads the current bot page or when the page reloads automatically. |
| ym_home | This event occurs when the user clicks the home icon in the bot. |
| ym_closed_promotion | This event occurs when the user closes any promotional content displayed within the chat widget. |
| page-url-based-trigger | This event occurs based on a specific URL or webpage. When the URL matches the loading page URL, a specific journey is triggered.|
### How to trigger bot-opened and bot-closed events
When a user clicks on the chat bubble to open the bot, the `bot-opened` event is triggered, and when the user closes the bot interface, the `bot-closed` event is triggered. These events can then be used to initiate specific flows or perform other actions based on the user's interaction with the bot.
#### Prerequisites to trigger bot-opened and bot-closed events
You need to follow the below prerequisites to trigger bot-opened and bot-closed events.
1. Navigate to **Deploy** > **Web** > **Experience on a Website**.
2. On the live chatbot page, **right-click** > **Inspect** > **Network tab**.
3. To view the API call details, **Refresh** your page and select **bot-load-details**.
4. Expand the skin of the widget to see that `sendEventOnOpen` and `sendEventOnClose` options are set to true.
#### Trigger bot-opened and bot-closed events
To trigger bot-opened and bot-closed events, follow these steps:
1. Select the respective environment and go to **Automation** > **Event** > **Widget**.
:::note
In the Live environment, you cannot enable the events.
:::
2. Navigate to the **bot-opened** and **bot-closed** events, click on the **More options** icon > **Activate**.
3. Go **Build** > select the flow for which you want to trigger the event > select the start trigger as **Event** and include either bot-opened or bot-closed event in the start node based on your preferred choice.
4. Refresh the Live bot page and open the bot to view the triggered flow based on the selected event.
---
## Facebook Comments
Integrating Facebook comments with the Yellow.ai Cloud platform helps automate responses to comments on your Facebook posts seamlessly.
This saves you from the tedious task of individually responding to each comment. Additionally, it improves user engagement and ensures prompt replies to inquiries and feedback.
With FB comments integration, you can engage in seamless two-way conversations.
:::note
[Facebook Messenger](https://docs.yellow.ai/docs/platform_concepts/channelConfiguration/facebook-messenger) and Facebook comments function as separate communication channels.
:::
The FB comments integration offers these features:
* **Automated replies to user comments:** It automatically responds to user comments and effectively manages conversations within each comment using bot flows.
* **Multi-user conversations:** When multiple users respond to a single comment, their responses are consolidated within the same conversation thread.
* **New conversations stand out:** When a new user comments separately, it starts a new conversation thread within the same comment.
* **Works with different message types:** It supports various message types like text, images, file sharing, and quick replies (which get converted into text messages).
## Setting up Facebook Comments bot
To set up Facebook comments bot, you need to perform the following:
* [Connect Facebook Comments to Yellow.ai](#connect-your-facebook-page-to-yellowai)
* [Setup a bot](https://docs.yellow.ai/docs/platform_concepts/get_started/account-setup#create-your-first-bot) on Yellow.ai platform based on your use case.
## Connect your Facebook page to Yellow.ai
To connect your Facebook page to Yellow.ai, you need to have a Facebook Business account with at least one Facebook page created.
:::note
To establish a connection, you must be an admin of the Facebook account and the respective Facebook page.
:::
### Link your Facebook page
To link your Facebook page, follow these steps:
1. On the left navigation bar, click **Extensions**.
2. Click **Channels** > **Messaging** > **Facebook messenger**.
3. Click **Connect**.
4. Login to your Facebook account that is connected to your Facebook Business Page.
5. After successfully logging in, click **Continue** to navigate to your page.
6. Select the business you want to grant Yellow Messenger access to, and click **Continue**.
7. Choose the specific business page you want Yellow Messenger to access, and click **Continue**.
8. Review the permissions that Yellow Messenger requires and click **Save**.
* Your Facebook page will be successfully connected to our platform.
10. Select your business page. If you have multiple business pages, select the one for which you want to set up a chatbot and then click **Continue**.
:::note
You can connect to an unlimited number of FB pages within a single FB business account.
:::
11. Toggle the button to connect the selected page to your bot. Then, choose either the **Comment to comment** option to reply to comments directly, or the **Comment to inbox** option to view and respond to comments in your inbox.
:::note
If you disable the toggle button, the option to select a **Comment response** will not be available.
:::
12. Click **+ Add Facebook page** to add multiple pages to your bot.
## Setup your bot
Before you start testing your bot, setup your bot with intents to automatically respond to user comments on your Facebook posts, as explained below.
* **Define bot's purpose and scope**: First, understand the scope and purpose of your bot (use case). Clearly outline what types of questions or requests the bot should handle based on your intended use case.
* **[Create Intents](https://docs.yellow.ai/docs/platform_concepts/studio/train/intents)**: Include the intents for common questions or requests. Add the utterances to each intent and train them to trigger the respective flow.
* **[Create flows](https://docs.yellow.ai/docs/platform_concepts/studio/build/Flows/journeys)**: Design customized conversation flows to manage responses to your FB posts. You can incorporate text, images, and file prompts within the flow. While quick replies are supported, they will be displayed as plain text in the bot's responses.
Once you set up the bot, verify whether the bot effectively handles and responds to user comments according to the defined expectations.
## Test your bot on Facebook page
Once you have linked your bot to your Facebook page through the Yellow.ai platform, you need to test the bot to verify whether the bot is able to respond to user comments on your Facebook page automatically.
To test your bot on Facebook page, follow these steps:
1. Open your Facebook account and navigate to your business page.
2. Add a comment to the Facebook page post to test the chatbot. Ensure that you have created the bot with intents and configured the flows with the same intent.
* When a user adds a comment to the post, if the intent matches, the bot should be able to understand the utterance and respond automatically.
* If the intent does not match, the bot should be able to respond with a fallback message.
3. If a flow is configured for agent reply using the [raise ticket](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/raise-ticket) node to start a conversation with an agent, it initiates a conversation with the agent. Once a conversation is initiated, the user can talk to the agent.
4. To view the entire conversation between the live agent and user, navigate to the **Inbox** module in the platform and select **Bot messages** in the **My Chats** section.
* When the conversation between the agent and user ends, the bot takes the conversation forward with the user.
### Test Facebook comments chatbot with FAQs
You can also add FAQs to the bot to simplify bot responses. For example, for a product-related post, you can add all the details related to the product as questions and answers. The bot can respond to customer questions based on the FAQs that you have added.
Similarly, you can test your Facebook comments chatbot by adding different options such as order updates, shipping information, and so on.
First, [add few FAQs](https://docs.yellow.ai/docs/platform_concepts/studio/train/add-faqs#-1-add-faqs) and train them. Then, test them to ensure that they work as expected.
---
## Facebook Messenger
Facebook Messenger (FBM) is a social media platform that allows you to interact with your users directly through Facebook business pages. FBM integration enables two-way conversations.
Businesses can use FBM chatbots to automate customer support, provide order updates, shipping information, and send promotional messages to their users.
This integration enables the following key features:
* **Automated Replies**: Provides the ability to automatically respond to user messages received in the FBM chat inbox.
* **Supported message types**: You can use various message types including text, image, videos, file, carousel, and quick replies, enhancing the communication experience.
:::note
Facebook Messenger and [Facebook Comments](https://docs.yellow.ai/docs/platform_concepts/channelConfiguration/facebook-comments) function as separate communication channels.
:::
**Watch the video on how to setup Facebook Messenger:**
## Limitations of Facebook Business Messenger (FBM) Chat
Option | Character limit
--------------------|----------------------
Character limit in each quick reply | 22
Maximum number of quick replies | 13
Character limit for the Carousel title | 22
Character limit for Text message | 2000
## Setting up FBM chatbot
To set up FBM bot, you need to perform the following:
* [Connect Facebook page to Yellow.ai](#connect-your-facebook-page-to-yellowai)
* [Setup a bot](https://docs.yellow.ai/docs/platform_concepts/get_started/account-setup#create-your-first-bot) on Yellow.ai platform based on your use case.
* [Test your FBM chatbot](#test-fbm-chatbot)
## Connect your Facebook page to Yellow.ai
To connect your Facebook page to Yellow.ai, you need to have a Facebook Business account with at least one Facebook page created.
:::note
To establish a connection, you must be an admin of the Facebook account and the respective Facebook page.
:::
To connect your Facebook page to Yellow.ai, follow these steps:
1. On the left navigation bar, click **Extensions**.
2. Click **Channels** > **Messaging** > **Facebook messenger**.
3. Click **Connect**.
4. Login to your Facebook account that is connected to your Facebook Business Page.
5. After successfully logging in, click **Continue** to navigate to your page.
6. Select the business you want to grant Yellow Messenger access to, and click **Continue**.
7. Choose the specific business page you want Yellow Messenger to access, and click **Continue**.
8. Review the permissions that Yellow Messenger requires and click **Save**.
* Your Facebook page will be successfully connected to our platform.
10. Select your business page. If you have multiple business pages, select the one for which you want to set up a chatbot and then click **Continue**.
:::note
You can connect to an unlimited number of FB pages within a single FB business account.
:::
11. Enable the toggle button to connect the selected page to your bot.
12. Click **+ Add Facebook page** to add multiple pages to your bot.
## Setup your bot
Before you start testing your bot, set up your bot with intents to automatically respond to user messages on their Facebook pages.
* **Define bot's purpose and scope**: First, understand the scope and purpose of your bot (use case). Clearly outline what types of questions or requests the bot should handle based on your intended use case.
* **[Create Intents](https://docs.yellow.ai/docs/platform_concepts/studio/train/intents)**: Add the intents that correspond to common questions or requests from users. Within each intent, add the relevant utterances and ensure they are trained to trigger the appropriate flow.
:::note
To trigger the respective flow in the FBM chatbot, you must add the utterances `get started` and `Get Started` and train them accordingly.
:::
* **[Create flows](https://docs.yellow.ai/docs/platform_concepts/studio/build/Flows/journeys)**: Design customized conversation flows to manage responses to your FBM. You can use the nodes such as name, email, phone number, quick reply, image, video, text, file within the flow.
Once you set up the bot, verify whether the bot responds to user according to the defined use case.
## Test Facebook Business Messenger
### Test FBM Chatbot
Once you have linked your bot to your Facebook page through the Yellow.ai platform, you need to test the bot to verify whether the bot is able to respond to user messages on their Facebook page.
To test your bot on Facebook page, follow these steps:
1. Open your Facebook account and go to your business page.
2. Click **Message**.
3. Click **Get Started** to start the conversation with the bot. Make sure you have already created an intent and added the utterances `get started` and `Get Started` to trigger the corresponding flow in your FBM chatbot.
* The FBM chatbot will trigger the relevant flow, and you can start interacting with the bot.
:::note
If you have not added the `get started` or `Get Started` utterances to your flow, the FBM chatbot will not trigger the intended flow. Instead, a fallback message will be displayed.
:::
4. If a flow is configured for agent reply using the [raise ticket](https://docs.yellow.ai/docs/platform_concepts/studio/build/nodes/action-nodes-overview/raise-ticket) node to start a conversation with an agent, it initiates a conversation with the agent. Once a conversation is initiated, the user can talk to the agent.
5. To view the entire conversation between the live agent and user, navigate to the **Inbox** module in the platform and select **Bot messages** in the **My Chats** section.
* When the conversation between the agent and user ends, the bot takes the conversation forward with the user.
:::note
To know about Facebook Messaging Policy, refer to the [Facebook doc](https://developers.facebook.com/docs/messenger-platform/policy/).
:::
### Test FBM chatbot with FAQs
You can also add FAQs to the bot to simplify bot responses. For example, for a product-related post, you can add all the details related to the product as questions and answers. The bot can respond to customer questions based on the FAQs that you have added.
Similarly, you can test your FBM chatbot by adding different options such as order updates, shipping information, and so on.
First, [add few FAQs](https://docs.yellow.ai/docs/platform_concepts/studio/train/add-faqs#-1-add-faqs) and train them. Then, test them to ensure that they work as expected.
## Facebook Business best practices
### Facebook Business verification process
As the verification process can take more than two weeks, we recommend starting the verification at the beginning phase of the project.
#### 1. Access Business Manager Security Center
To start the verification process, go to *Security Center* and click **Start Verification** in the Business verification section.
The **Start Verification** button will be greyed out unless your business needs access to certain features. See the below section on how to enable the button.
#### 2. Select your Business
If your business is already listed:
1. **Confirm your business details**
- Select a phone number that you have access to from the drop-down menu and click **Next**.
- Double check for any typos or other errors: you will not be able to edit this information upon submission.
2. **Get a verification code**
- Choose to receive the verification code on your business phone number via a text message or a phone call, or via email. Note that the phone number option may not be available in all countries.
- Please make sure that the email registered has the same domain as the website. **Accepted Values**: Email: name@business.comSite: www.business.com
:::note
The following examples are not accepted:
- Email: name@gmail.com or name@otherbusiness.com
- Site: www.business.com
:::
3. **Get a verification code**
- Choose to receive the verification code on your business phone number via a text message or a phone call, or via email. Note that the phone number option may not be available in all countries.
- Please make sure that the email registered has the same domain as the website.
4. **Verify your domain**
- If your domain is already verified, click **Use Domain Verification**. If not, complete the domain verification process, then return to the Security Centre and select **Continue**.
- Enter verification code (not applicable if you use domain verification)
- Enter your verification code. Click **Submit**.
- You can skip the remaining steps 3 & 4 below.
:::note
- If you cannot see your business in the list, please select **None of these matches**. Then proceed with [Steps 3](#3-verify-the-legal-business-name) and [Step 4](#4-verify-the-business-address-or-phone-number) below.
:::
#### 3. Verify the Legal Business name
You may be asked in step 3 to provide official documentation of your business's legal name.
Upload an official document that matches the business's legal name you entered in step 1, such as a business license, articles of incorporation, or business tax registration.
- Please check [here](#documents-checklist) for the list of the documents accepted and not accepted before submitting them.
#### 4. Verify the Business Address or Phone Number
- Upload a document that shows both the legal name of your business and the mailing address or phone number shown on the screen.
- Please check [here](#documents-checklist) for the list of the documents accepted and not accepted before submitting them.
When your business is verified, you will be notified, and you will also see the verified status in your account.
### Checklist for Facebook Business Verification
To increase the company's chances of being verified by Facebook, it is important to have the following items checked internally by the respective Business Analysts (BAs) of the projects:
- The company's website is active and complete, containing the company's name and address.
- The account email is from the same domain as the company's website provided in the documentation. (www.mywebsite.com > xyz@mywebsite.com).
- If the verification will be made through the phone number, make sure the number is able to receive the call. If the phone has IVR, ask the client to disable it temporarily.
- The company's trade name in the documentation is the same as used on the website and on the Facebook page. If different, the names need to be related in some way on the website. For example, at the footer, enter "Company ABC powered by company D."
#### Documents checklist
- Document quality / resolution should be good - no pixelation.
- Documents should always be signed, especially GST and other accepted documents.
- Documents should not be modified or show signs of tampering (e.g., handwritten notes, strikethroughs, white ink, etc.).
- The legal business documents should have a matching address. If not, please provide additional documents that prove the address.
- English documentation seems to be processed more quickly; currently, the following languages are supported for business verification:
#### Website checklist
- Website should be accessible, with no geo filters that may prevent FB teams from viewing the website.
- The website should be secure (https://).
- The website must contain the legal business name, preferably on the home page (e.g., in the footer of the website).
- The website domain and email domain (for OTP verification) must be the same. If not, upload DNS records to prove that the legal business entity owns both domains. Another option is domain verification. It is helpful to have ownership of the provided domain.
- Upload the website to FB Business Manager.
#### Duration
As the verification process can take more than two weeks, we recommend starting the verification at the beginning phase of the project.
#### Check out Facebbok's official documentation
* [Verify your business](https://www.facebook.com/business/help/2058515294227817?id=180505742745347)
* [Documents to upload](https://www.facebook.com/business/help/159334372093366)
* [Troubleshooting when the business is not verified](https://www.facebook.com/business/help/2342133782492969?id=180505742745347)
---
## Facebook Lead Ads Configuration
## Facebook Lead ads
On Facebook, the brands can roll out forms for generating interest and leads among the Facebook users (or potential customers).
### Pre-filled forms
The major problem with respect to filling forms in general is the poor form completion rate. The users abandon the form perhaps due to more no.of questions.
The FB’s pre-filled forms solve this problem by pre-populating the KYC questions such as name, contact number, email ID. This way the interested usee is expected only to answer the primary requirement they have/the problem they face.
This potentially increases the form completion rate.
## The integration with FB’s lead ads
### The process has two parts
1. Requirements and form creation
2. Lead data storage in the Yellow.ai’s backend
### Requirements and form creation
1. A valid [business page](https://www.facebook.com/business) on Facebook for the brand
2. A link to [privacy policy](https://en-gb.facebook.com/business/help/1247534515288168?id=735435806665862) on what all info you will collect, how do you intend to use the data etc
3. A valid website URL of the brand
4. A relevant name of the form based on the set of questions (e.g, Yellow Beauty free expert consultation)
5. Add the actual questions the brand intends to ask
6. A relevant description of the form
## Lead data storage in the Yellow.ai’s backend
1. Inside the Yellow.ai platform, navigate to Configuration → Channels
2. Under Channels, select the ‘Facebook Lead Ads’ option
3. Now, tap on ‘Connect with Facebook’ and login with the brand’s account login credentials
4. After successfully logging in, our platform gets connected with the FB account.
5. Now, select the Facebook page associated with your brand that you want to integrate with the Yellow.ai platform.
6. The page ID and access token gets auto-filled
7. Select the Unique ID (UID) based on the form you created and click on ‘Connect’.
8. Once successfully connected, test the flow from form submission to lead storage in YM’s backend. Go to ‘Lead Ads Testing Tool’.
9. Test the form submission flow by choosing the brand’s associated page and the form created already.
10. The leads captured live get stored onto the Yellow.ai’s backend which can be used by the brand for customer engagement.
Congrats! With this, you have understood how to configure 'Facebook Lead Ads' to the Yellow.ai platform.
---
## Facebook Workplace
Facebook Workplace is an online collaborative tool that helps businesses and organizations to communicate and collaborate with internal team members. Using this tool, you can create various channels that help you to manage work-related activities such as group discussions, project management; file, image, or video sharing, and updates related to specific projects. You can have both public and private channels.
On Facebook Workplace, bots are represented as pages. A page is automatically created for a custom integration app. Only system administrators of a workplace community can create apps and generate access tokens in that community.
## Character limitations of Facebook workplace channel
In this section, you can view the character limitations of Facebook workplace channel.
### Message types
Message types options | Character limit
----------------------|------------------
Text | The maximum number of characters supported is 2000.
Image | The maximum size of an image is 8 MB.
Video, audio, and other file types | The maximum size is 25 MB.
### Quick Reply
Quick Reply options | Character limit
--------------------|---------------
Quick reply title | The maximum number of characters supported is 2000.
Quick Reply buttons | A maximum of 13 quick reply buttons are supported.
Quick Reply button title | The maximum number of characters supported is 20.
### Carousel
Carousel options | Character limit
--------------------|---------------
Cards | A maximum of 10 cards per message is supported.
Title | The maximum number of characters supported is 80.
Subtitle | The maximum number of characters supported is 80.
Buttons | A maximum of 3 buttons per card are supported.
## Setup Facebook workplace channel using developer portal
You need to register for a new system admin account in the [Facebook Workplace](https://yellowtest150.workplace.com/) Developers Portal (`https://.workplace.com/work/admin`) to create a Facebook Workplace channel.
To setup Facebook workplace channel to your bot, configure the following:
* [Create Custom Integration](#step-1-create-a-custom-integration)
* [Get App ID, App Secret, and Access token](#step-2-get-app-id-app-secret-and-access-token)
* [Provide Permissions to interact with your bot](#step-3-provide-permissions-to-interact-with-your-bot)
### Step 1: Create a Custom Integration
To create a Custom Integration, follow these steps:
1. Log in to your Facebook Workplace admin account and click **Integrations**.
2. On the *Home* page, click **Admin Panel**.
3. Click **Create Custom Integration** to provide authorization to create a channel between Facebook Workplace and Yellow bot.
4. Under *Create Custom Integration*, enter the following details:
i. Enter the **Name** of your integration.
ii. Enter a short **Description** of your integration.
iii. Click **Create**.
* You will see the integration details. You can update the integration details if required.
### Step 2: Get App ID, App Secret, and Access token
To get the App ID, App Secret, and Access token from Facebook Workplace developer portal, follow these steps:
1. On the Integration details page, click on the below highlighted icon and copy the **App ID** and **App Secret**.
2. Click **Create access token**.
3. Select the **I Understand** box to agree to access token guidelines and click **Copy** to copy the access token, then click **Done**.
:::note
* Access tokens cannot be retrieved but new token can be generated.
:::
### Step 3: Provide permissions to interact with your bot
You need to select your preferred permissions for your users to interact with the bot in the workplace.
To grant permissions, follow these steps:
1. On the Integration details page, click **Permissions**.
2. Select the following permissions:
* **Message any member** - Send a message to any member in the workplace.
* **Read user email** - See any group member's email address.
* **Read work profile** - See any group member's complete profile, including phone number, department, and location.
* Click **Save**.
## Connect Facebook workplace to your bot
#### Prerequisite
* Copy the App ID, App Secret, and Access token from the developer portal to connect the Facebook workplace channel to your bot on the platform.
To connect Facebook workplace channel to your bot on the platform, follow these steps:
1. On the left navigation bar, click **Extensions**.
2. Click **Channels** > **Messaging** > **Facebook workplace**.
2. Enter the **App ID**, **App secret**, **Access token** that you have copied from the workplace developer portal admin account and click **Save**.
* Your Facebook workplace channel will be successfully connected.
3. Navigate to the **Overview** page, under the **Active channels** section, to verify that the Facebook workplace channel is successfully connected to your bot.
## Configure Webhook for custom integration
After connecting your bot to the Facebook workplace channel, you need to subscribe to events under **Page** section of the *Configure Webhooks*.
To setup a Webhook on the workplace, follow these steps:
1. On the Integration details page, click **Webhooks**.
2. Click **Edit** icon corresponding to the Page.
3. By default, a callback URL is displayed after successfully connecting your bot to the Facebook workplace channel. Select **messages** and **messaging_postbacks** and click **Save**.
## Test your bot on Facebook workplace
After connecting your bot to the Facebook workplace, you can test your bot.
#### Prerequisites
* Ensure that you have created the bot with intents and configured the flows with the same intent. For more information, click [here](https://docs.yellow.ai/docs/platform_concepts/get_started/createfirstbot).
To test your bot on Facebook workplace, follow these steps:
1. Go to your Facebook workplace developer account.
2. On the Home page, select your bot.
3. Start the conversation to test your bot based on the configured flow.
---
## Customize chat bot using functions
Yellow.ai offers a wide range of options to customize features for its web widget. However, sometimes our clients might need even more flexibility in crafting the widget’s design, and functionality unique to their use cases. There are certain tricks that you can use to customize your web widget to suit your business needs.
If you have integrated Yellow AI’s chat widget on Android/iOS app, see [Android chatbot SDK](https://docs.yellow.ai/docs/platform_concepts/mobile/chatbot/android) and [iOS chatbot SDK](https://docs.yellow.ai/docs/platform_concepts/mobile/chatbot/ios).
This section guides you with different ways to customize your chat widget’s visibility and functionality.
In this article, you will learn:
* [How to customize the visiblity of bot icon on the website?](#customise-the-appearance-of-your-chat-widget)
* [How to trigger a flow using functions?](#trigger-specific-flow-using-function-in-the-payload)
## Customise the appearance of your chat widget
If the bot’s default customization settings do not match your brand guidelines, or if you do not want to display the bot right after the page load, you can use the following steps to set up the bot in a way so that it is displayed only when you want it to.
First you will have to insert the default script given to you by yellow.ai at the `