Troubleshooting an integration for advanced AI agents

What's my plan?

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:

• Test the integration in the integration builder
• Check that the request parameters match
• Check the conversation logs for session parameters
• Output raw values in the failure scenario
• Check the HTTP status code
• Investigate any technical errors in the dialogue

Related articles:

• Integration builder resources

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.