Custom Order Tracking API integration

Easily connect your custom tracking system to Zipchat by following these steps:

How to Set Up Custom Order Tracking

1. Share API Documentation

   • Forward your Custom Order Tracking API documentation to your developer to enable integration with Zipchat.

2. Implement the Endpoint

   • Have your developer create an API endpoint in your system that Zipchat can call to check order statuses.

3. Add the Endpoint and API Key

   • Input the API endpoint URL and API key into Zipchat’s configuration settings to establish a secure connection.

4. Provide Order Format

   • Specify an example order format for testing.

5. Enable Order Tracking

   • Activate the order tracking feature from the Chat Settings or Configuration section.

6. Test the Setup

   • Use the Test Chat tool and ask, "Where is my order?" to verify the integration.

---

Key Components

• API Key: A unique key to authenticate Zipchat with your internal system.

• Order Tracking API Endpoint: The custom API endpoint your system provides for retrieving order details.

You can also find this guide on Notion.

About the API

• The custom order tracking API endpoint allows you to provide Zipchat's AI agent with access to your order database so it can help customers with their order status and tracking information.

• Whenever a customer asks about order tracking, Zipchat will collect their order info and email.

• Once the agent has the right information, it will call the custom endpoint provided by you, expect to receive context, and generate a reply based on the context that you provided.

Prerequisites

In order to connect the custom endpoint to your chat, we'll need the following things from you:

• Endpoint URL

• API key

• Order number format (used so Zipchat knows what to look for, e.g., "#1001", "5555", etc.) - this should be a number that the customer has access to so they can provide it

This guide is for developers implementing the response handling for the Order Lookup Service. Your system will receive GET requests and should respond according to the specifications below.

Implementation

Incoming Request

You will receive GET requests with the following characteristics:

• Endpoint: [Your endpoint URL]

• Authentication: [ Your API Key ] in x-api-key header

• Query Parameters:

  • order_id: string (required)

  • customer_email: string (required)

Authentication

Validate the API key provided in the x-api-key header. If invalid or missing, return a 401 Unauthorized response.

Responses

1. Found Order (Status 200 OK)

When an order is found, respond with:

• Status: 200 OK

• Content-Type: application/json

• Body:

  
  {
    "context": "string",
    "tracking_url": "string"
  }
  

Context Field

The context field is crucial for guiding an AI agent's response to the customer. It should:

• Provide clear, concise information about the order status

• Include relevant order details

• Optionally include policy information

Examples:

• "Order 123 found. It includes 1 x Product X, 2x Product Y. Not shipped yet, normally ships in two days."

• "Order 456 is on its way, can be followed via the provided tracking link."

• "Order 789 found but not shipped. Contact support for further assistance."

Tracking URL Field

If available, provide a URL where the customer can track their order. If not applicable, this field can be null or omitted.

2. Order Not Found (Status 404 Not Found)

When an order is not found, respond with:

• Status: 404 Not Found

• Content-Type: application/json

• Body:

  
  {
    "context": "string"
  }
  

Context Field for Not Found

Provide information about the order not being found and suggest next steps.

Examples:

• "No order found with the provided details."

• "Order not found - please double-check your order number."

• "Order not found - contact support for further assistance."

3. Unauthorized Access (Status 401 Unauthorized)

When the API key is invalid or missing:

• Status: 401 Unauthorized

• No body required

Implementation Notes

1. Ensure all responses use the correct Content-Type header: application/json.

2. The context field is critical for customer communication. Make it informative yet concise.

3. ‼️ Important: For maximum flexibility, we will not include status information into the AI Agent context - always include information if an order was found or not in the context

Testing

• You can use Postman to send the described request while developing

• Afterwards you can send us details about the endpoint and we’ll validate everything works

Timeouts

• All requests have a 5 second timeout rule. If no response is received within 5 seconds, the Agent will respond that it couldn’t check the order status at this point.

Support

For any questions about this implementation, please contact [e-mail]