Recent searches


No recent searches

Chloe Brown's Avatar

Chloe Brown

Joined Feb 19, 2025

·

Last activity Feb 21, 2025

Following

0

Followers

0

Total activity

7

Votes

0

Subscriptions

0

ACTIVITY OVERVIEW

Latest activity by Chloe Brown

Chloe Brown created an article,

ArticleUsing AI agents - Advanced
Add-on AI agents - Advanced

The integration builder can be used to create a Zendesk ticket from a conversation using an AI agent. This article will take you through the steps on how to do so.

For reference, you can find the relevant Zendesk developer documentation on this here.

This article contains the following topics:

Prerequisites

Required to get set up you will need:

  • Your Zendesk subdomain
  • Your authorization token (see the section below for more information)

Create integration

  1. Create a new Integration in API Integrations.
  2. Give it a name such as Create Zendesk Ticket and a description.

Environment and endpoint

To access the Zendesk Ticket API, you will need to make a POST request to the following endpoint: http://[your-zendesk-subdomain].zendesk.com/api/v2/tickets

With your Zendesk subdomain, you can construct the endpoint URL to your Zendesk instance. This URL is then used in the Environments section of the integration builder to make the POST request.

  1. Navigate to the Environments section of the integration builder.
  2. For Method type, select POST.
  3. Add your constructed URL endpoint for the Ticket API.

Auth

To access the Zendesk API, you will need to create a token in Admin Center.

  1. In Admin center, go to Apps and integrations and select APIs > Zendesk API.
    You will see the below screen where you can add a new token.
  2. Click Add API token.
  3. Give it a name such as Create Ticket.
  4. Copy the token somewhere safe, as you will need this for setting up the integration in the integration builder.

Once you have these, you can add them to your integration in the integration builder.

  1. In the Environment section, click Authorization.
  2. In Authorization type, select Basic Auth.
  3. Enter an admin email address with /token appended at the end.
  4. Paste your created token as the password.
  5. Make sure to include the authorization token in the request by manually constructing it in the headers.

Request Parameters

This is where you will be passing data from the AI agent conversation into the integration to create the ticket.

For the live integration, you will need to set the parameters on your dialogue and then match these to your request parameters in the integration builder. For testing purposes, you can create the request parameters with test values as we are not using live data from a conversation.

Make sure that your request parameter names match those that you have set in your dialogue (via actions). See Building in the dialogue builder for more information.

Body

The body is where you are going to send all of the data from the conversation to create the ticket via the Ticket API. The structure of this body must match the schema for the Ticket API.

To see the schema and which fields can be created with your ticket, see the Zendesk developer documentation here.

Below is an example request body with the request parameters we created earlier.

Test the integration by clicking Test Production.

You should then be able to see your newly created ticket in your Zendesk dashboard.

Chat transcript formatting: Standard vs HTML body

The Ticket API supports either body or html_body for comments. When using body, multiple consecutive spaces are collapsed into a single space and multiple new line (“/n”) characters are collapsed into a single new line. Whereas, when using html_body, you're able to use standard HTML syntax for your comment formatting.

For more information, see the Zendesk developer documentation here.

To use either in your created ticket, you'll structure the one you want to use in “comment” in the request body.

Note: Use either option, not both as in the demonstration below.

If you're sending the chat transcript from the conversation, then it's recommended that you use the reformat values tool to make the transcript more readable. Rather than just being one big chunk of text, you can add line breaks for the beginning of each message. 

If you're sending an HTML body, then you can use the Reformat values tool to add your HTML.

For instructions on how to use the Reformat values tool, see Reformatting values in request parameters for advanced AI agents.

In the screenshot below, we've reformatted the chat transcript to make clickable URLs and added line breaks with
.

Standard fields vs Custom field values

In addition to the standard fields that can be created and sent in the body of the request, you can also create custom field values. For instructions on how to set up custom fields in the body, see the Zendesk developer documentation here.

Building in the Dialogue Builder

  1. Add the API Node and select the Create Zendesk Ticket integration that you created above.
  2. Create an action on the API node which sets the parameters from the conversation.
    It will look something like this:
  3. Add a message for the Success and Fallback scenarios.

Edited Feb 21, 2025 · Chloe Brown

0

Followers

1

Vote

0

Comments


Chloe Brown created an article,

ArticleUsing AI agents - Advanced
Add-on AI agents - Advanced

When using an advanced AI agent for customer support, it’s helpful to know when a human agent is available to step in. The Agent Availability API helps with this by allowing your AI agent to check the availability of specific agents or groups of agents based on certain criteria.

The API provides detailed information about each agent’s status, including whether they’re online, away, or offline for different channels like messaging. It also shows their overall availability across all channels, the tasks they’re currently handling, and their workload limits for specific channels.

By using the Agent Availability API, you can make your AI agent smarter when it comes to handing off conversations, routing customer queries to the right agent, or tracking agent availability or estimated wait times.

In this article, we’ll show you how to set it up so your AI agent and support team can work together more efficiently, giving customers faster and more precise help.

This article contains the following topics:

Prerequisites for setting up the Agent Availability API in the integration builder

To set up the Agent Availability API in the integration builder, you'll need to gather the following key information:

  • The Zendesk subdomain. This is the name of your company within your Zendesk instance. This is needed for the URL to make the call to the API using the integration builder.
  • Auth token and an admin email. Created in Admin Center, this token will authorize your AI agent to make the request for the Agent Availability data.
  • Any group ID (if applicable). If you want to filter for online agents belonging to a specific group, you can do so with a URL query.

Creating a token to access the API 

To access the Zendesk API, you'll need to create a token in Admin Center.

To create an API token

  1. In Admin Center, click Apps and integrations in the sidebar, then select APIs > Zendesk API.
  2. Click Add API token.
  3. Give the token a descriptive name, such as Agent Availability.
  4. Copy the token somewhere safe, as you'll need this for setting up the integration in the integration builder.

Creating the integration in the integration builder

  1. Create an integration in the integration builder.
  2. Go to the Environment tab and select your chosen environment (for example, Production, or you could change this to something more descriptive such as getAgents).
  3. Set up the endpoint using the following format, replacing [your-subdomain] with your subdomain:
    https://[your-subdomain].zendesk.com/api/v2/agent_availabilities
  4. (Optional) Further customize the query URL by filtering.
    • Example 1: If you want to check how many agents are online now in the messaging channel:
      https://[your-subdomain].zendesk.com/api/v2/agent_availabilities?filter[channel_status]=messaging:online
    • If you want to check for agents available online and in a specific service group:
      https://l[your-subdomain].zendesk.com/api/v2/agent_availabilities?filter[channel_status]=messaging:online&filter[group_id]={{groupId}}
      For more information, see Agent Availability API.
  5. On the Authorization tab, set the Authorization type to Basic Auth.
    • Username: Your admin email address with ‘/token’ appended (for example, admin@yourcompany.com/token).
    • Password: Paste the API key you generated earlier in Admin Center.
  6. On the Headers tab, click Add Header.
  7. In the Key field, enter Authorization
  8. In the Value field, enter Basic {{apiToken}}.
  9. (Optional) If you're checking for a particular groupId, then you can either add it statically to the URL query or you can create a dynamic link by creating a parameter in Request parameters with a key such as groupId and adding &filter[group_id]={{groupId}} to the URL (as demonstrated in step 4).

With that all set up, you should be able to successfully test your integration to view the response.

For the success scenario, you can now add your session parameters. Here are three commonly useful example parameters:

  • agentCheck: Provides an array of relevant available agents.
    • In the dialogue builder, use a conditional block with Includes.
  • availableAgent: Provides number of relevant available agents.
    • In the dialogue builder, use a conditional block with Greater/Less Than.
  • estimatedWait: Divides number of open work items by active agents, multiplied by average handling time. This value is in minutes.
    • In the dialogue builder, use a conditional block with Greater/Less Than.

These parameters are now available for use in the dialogue builder with an API node that calls the Agent Availability integration you built in the integration builder.

Edited Feb 19, 2025 · Chloe Brown

0

Followers

1

Vote

0

Comments


Chloe Brown created an article,

ArticleUsing AI agents - Advanced
Add-on AI agents - Advanced

When using the integration builder, you can pass request parameters of types such as string, number, boolean, and array in the API request body. This functionality enables greater flexibility in API integrations and supports a wider range of use cases. In this article, we’ll guide you through the process of configuring these parameters.

This article contains the following topics:

Related articles:

Setting the parameter type in request parameters

To set the parameter type in request parameters

  1. Navigate to the Request Parameters section in the integration builder.
  2. Define your parameter and set its type as one of the following:
    • String: For textual data enclosed in quotes (for example, "example text").
    • Number: For numerical values (for example, 123).
    • Boolean: For true/false values.
    • Array: For a collection of values (for example, ["item1", "item2"]).

Add reformatting for array parameters

For testing purposes in the integration builder with parameters of type array, you must add a reformatting function to ensure proper handling of the data type. To do so, use the following function:

$eval($)

This function parses the string value into an array object.

If the parameter is already an array object, the function will not alter its behavior.

For more information, see Reformatting values in request parameters for advanced AI agents.

Using parameters in the API call request body

In the API call request body, these parameters can be used in the same format as string parameters, using the syntax: {{}}

While the parameter may visually appear as a string in the body—as you can see in the screenshot below—during execution it will transform into the corresponding data type specified in the Request Parameters section.

Testing your configuration

Use the Test Production button in the integration builder to execute your API call.

Verify that the parameters are being passed with the correct types (string, number, boolean, array) in the request.

Review the response to ensure proper handling by the API.

Note: Successful transformations depend on correctly setting up parameter types and reformatting functions. Misconfiguration may lead to errors in API calls.

Edited Feb 19, 2025 · Chloe Brown

0

Followers

1

Vote

0

Comments


Chloe Brown created an article,

ArticleUsing AI agents - Advanced
Add-on AI agents - Advanced

You may have an API that can accept multiple request parameters, yet not all are mandatory to make a successful call. If a parameter is expected but not provided, the integration may fail because the API expects a valid value—whether an empty string `””` or `null`. In that case you will need to nullify these parameters in the integration builder so that the call does not break.

To nullify optional parameters

  1. Understand optional parameter behavior.
    First, make sure that your API can gracefully handle optional values as either an empty string or `null`.
  2. On Chat Start, initialize the optional parameters to null or an empty string.
    This will prevent the API call from failing when a parameter is omitted. For more information, see About actions for advanced AI agents.

  3. In the integration in the integration builder, make sure that the parameters are collected as request parameters and that the check box for Required is unchecked.
  4. Hover over the Test value input box until you see the symbol for reformat values.

    When you click this, a dialog appears. Here, you want to add the following JSONata expression to the text box that says “Reformatting JSONata”:
    ```$a and $not($a = "null") ? $a : ""```
    This JSONata expression will check whether the parameter exists and has a value.

Now when you have a value that is optional for your API call, it will be handled by the integration builder seamlessly.

Edited Feb 19, 2025 · Chloe Brown

0

Followers

1

Vote

0

Comments


Chloe Brown created an article,

ArticleUsing AI agents - Advanced
Add-on AI agents - Advanced

While REST APIs have long been a standard for enabling integrations, GraphQL is rapidly gaining traction due to its flexibility and efficiency. You can leverage the integration builder's features to integrate with GraphQL APIs. You can take advantage of GraphQL’s key features, such as requesting only the data you need and handling complex queries with ease.

In this article, we’ll walk you through the process of setting up a GraphQL request using the integration builder, from understanding the GraphQL schema to constructing queries and integrating responses into your conversations.

To set up a GraphQL request

  1. Find the GraphQL endpoint URL, usually provided by the API documentation (for example, https://api.example.com/graphql or for Shopify: https://{{storeName}}.myshopify.com/admin/api/2023-04/graphql.json).
  2. Add it to the integration builder interface.
    1. Navigate to Environments and select the POST method type (if you are requesting data).
    2. Add your GraphQL endpoint into the URL input.
  3. Select your authentication method (if required).
  4. If needed, add your credentials to the headers. For example, if it’s a Shopify integration, it will look like this:
  5. Understand the GraphQL Schema to select the data that you want returned from the server.
  6. Obtain the schema from the GraphQL server.

    It defines the available queries, mutations, and types. Use tools like Postman, GraphiQL or Apollo Explorer to inspect the schema, and to test and refine the query.

    We recommend obtaining the query from Postman by navigating to the Code snippet tab and checking for data where you should see an object with the key “query”. Copy the object to use in the next step.
  7. In the Body tab, add the GraphQL query specifying the data you need or the action you want to perform (if making a mutation request to modify data; create, update, delete).
    This must be in JSON format.
    Example query:
    ```{"query":"{\n __type(name: \"Order\") {\n name,\n fields {\n name\n type {\n name\n kind\n }\n }\n }\n}","variables":{}}```
  8. Navigate to the Success scenario to add your session parameters.
  9. Using JSONata, write your queries to access and transform (if needed) the data in the response. See below for an example:

Edited Feb 19, 2025 · Chloe Brown

0

Followers

1

Vote

0

Comments


Chloe Brown created an article,

ArticleUsing AI agents - Advanced
Add-on AI agents - Advanced

You might need to troubleshoot an integration between the AI agents - Advanced add-on and another system if it isn’t behaving the way you expect. This article outlines a number of troubleshooting steps you can perform to attempt to identify an integration issue.

This article contains the following topics:

Related articles:

Test the integration in the integration builder

As your first step in troubleshooting an integration, test it in the integration builder. Make sure that you’re getting a response and that you see the right data in the session parameters.

Check that the request parameters match

The request parameters you’re using in the integration builder—whether in the URL query, body, or header—must exactly match those captured in the dialogue.

Ensure the following:

  • There are no typos.
  • If you updated the spelling or name of a parameter at any stage in the dialogue, you also updated it in the integration.
  • The case matches exactly. Parameters are case-sensitive.

Tip: We recommend adopting a consistent naming convention for all your request or session parameters, such as lowerCamelCase or snake_case.

Check the conversation logs for session parameters

Check the conversation logs for more information, such as session data. You can search for conversations using the API by filtering for tags. If the conversation uses the API then you will be able to search for it.

When you are in conversation logs, at the top left, click Add filter.

On the menu on the left, navigate to Labels.

Here you can filter for the integration by name and by the scenario such as whether it was success, failure, or if there was an API error.

For integrations built in the integration builder, they will be prefixed by API, followed by the name of the integration and then end with the name of the scenario.

An example from the screenshot below is API-Chloe Demo: Apple Cart-Success:

  • API = prefix
  • Chloe Demo: Apple Cart = Name of the integration
  • Success = name of scenario

As a quick look to see if an integration, you can also hover over the tag symbol on a conversation log to see the tags associated with the conversation.

If you only want to see why a conversation with an API errored, in the Labels search, search for apiError.

Then, select your conversation to see more information.

When you are in the conversation, you can check what exists in the session data.

To do this, click Details in the top right.

Once you click this, you will see the Conversation Overview. Next, click Session Data.

Now you can see the session data in the chat. Out of interest here, we see at the bottom, the session parameters coming from the API integration.

Check the dialogue for session parameters

To quickly check that the session parameters exist for the session you can log them in an AI agent message via the dialogue. This is safest to do when testing the dialogue in a staging environment or, if the integration is live, make sure that you do not save the dialogue when testing.

In the AI agent message below, the session parameters are being logged so that they are visible when testing.

Output the raw values into a failure scenario

Make a string of all the data in the response by wrapping ‘data’ in the function `$string(data)`. This can then be logged in the failure scenario when testing to quickly see what is being returned.

Check the HTTP status code

When you test the integration, make sure to check the http status code that is returned. You will see this in the response on the right with the key of `statusCode`.

2xx: Success

  • 200 OK: The request was successful, and the server responded with the expected data.
    • This is the ideal response when testing an integration.

4xx: Client errors

Errors in this range generally indicate an issue with the request sent in the integration builder.

  • 400 Bad Request: The server could not understand the request due to invalid syntax or missing parameters.
    • Check the request payload for errors, missing fields, or incorrect formatting.
  • 401 Unauthorized: Authentication is required but was not provided or is invalid.
    • Verify the API key, token, or other authentication credentials. Double-check authorization headers.
  • 403 Forbidden: The server understood the request but refuses to authorize it.
    • Ensure that your IP addresses are allowlisted, or verify permissions for the API.
  • 404 Not Found: The requested resource could not be found on the server.
    • Check the URL or endpoint. Ensure the correct path is being used and the resource exists.

5xx: Server Errors

Errors in this range typically indicate an issue on the backend server.

  • 500 Internal Server Error: A generic error indicating that something went wrong on the backend server.
    • Contact the backend team with details of the request for further debugging.
  • 502 Bad Gateway: The server received an invalid response from an upstream server.
    • This often indicates an issue with the backend's internal services or dependencies.
  • 503 Service Unavailable: The server is currently unable to handle the request, possibly due to overload or maintenance.
    • Retry after some time, and check if there is scheduled downtime.
  • 504 Gateway Timeout: The server did not receive a timely response from an upstream server.
    • Ensure the backend service is operational and check for latency issues.

Investigate any technical errors in the dialogue

Sometimes, you might see a message with a technical error. A technical error includes the following text:

“I'm really sorry, there seems to be a technical problem. I hope I'll be back to working order soon.”

In this scenario, the issue is most likely a dialogue error, rather than anything related to the integration itself. Here are some tips:

  • Check the dialogue to ensure that the flow reaches the integration. Use buffer messages to confirm, and check for issues like mixed button functionalities, broken links, or circular references.
  • Verify that any required parameters are present. Missing required parameters will trigger errors before the integration runs.
  • For dynamic content, such as cards and carousels, ensure that all fields are populated. Undefined, blank, or null values can break these components and cause errors.

Edited Feb 19, 2025 · Chloe Brown

0

Followers

1

Vote

0

Comments


Chloe Brown created an article,

ArticleUsing AI agents - Advanced
Add-on AI agents - Advanced

Obfuscating API keys in an integration is essential for safeguarding sensitive data and preventing unauthorized access to protected resources. When an API key is entered into the integration builder, it’s automatically obfuscated to enhance security.

This article contains the following topics:

Related articles:

Using an authorization token in a request header

For authentication, ensure the authorization token is included in the request headers by referencing it as {{apiToken}}. This setup applies to all authorization types, except for cases with no authorization.

To implement the token within the headers, assign it to the designated header key using the syntax {{apiToken}} for OAuth 2.0, Bearer {{apiToken}} or, for Basic Auth, Basic {{apiToken}}.

How to:

In my example below with Authorization type of API Key, I have typed in my API key:

Once I click Save, it will automatically obfuscate the key to :

Now I click Headers. Here, I enter my token key and for the value I enter {{apiToken}}.

Using an authorization token as a request parameter

Additionally, a token can be passed as a request parameter, either directly from the widget or from metadata.

How to:

Define a request parameter with a key of your choice.

Once created, this parameter can be dynamically referenced within the headers in the same format as outlined above or it can be posted to an endpoint in the request body/payload.

Edited Feb 19, 2025 · Chloe Brown

0

Followers

1

Vote

0

Comments