User identification API

Overview

If your platform uses its own authentication system, you can pass an external_user_id to the widget during initialization. Our server will then fetch real-time user data (name, email, phone) directly from your API to populate the support dashboard.

⚙️ Configuration

Follow these steps to link your database:

1. Enable Integration: Navigate to Project Settings > API Integration and toggle it on.

2. Set Endpoint URL: Provide the URL where our server can fetch user data.

   • Path Variable: https://api.yoursite.com/users/{id} (Recommended)

   • Query Parameter: https://api.yoursite.com/users (Defaults to ?id=123)

3. Authentication: Add any necessary headers (e.g., Authorization: Bearer <token>) to secure the request.

API Specification

When a session begins, our server executes a GET request to your provided endpoint.

Method: GET

Timeout: 10 Seconds

Auth: Custom headers supported

✅ Expected Response Format (200 OK)

Your API must return a JSON object. While all fields are optional, providing them ensures a better experience for your support agents.

JSON

{
  "first_name": "John",
  "last_name": "Doe",
  "email": "john.doe@example.com",
  "phone_number": "+1234567890",
  "metadata": {
    "subscription_plan": "Pro",
    "signup_date": "2023-11-15",
    "company": "TechCorp"
  }
}

⚠️ Error Handling

Our system interprets HTTP status codes as follows:

• 200 OK: Success. The user profile is updated in the support dashboard.

• 404 Not Found: User not recognized. The widget will treat the visitor as a new profile using the provided ID.

• 401 / 403: Unauthorized. The request failed; please check your API keys or Header configurations.

• 5xx: Server Error. The request is aborted, and the issue is logged.

💡 Pro Tips

• Speed Optimization: Ensure your endpoint is fast. With a 10-second timeout, slow database queries may prevent user data from appearing in the widget promptly.

• Leverage Metadata: Use the metadata field to pass critical context (e.g., subscription plan, last order ID). This empowers agents to resolve issues without asking repetitive questions.

• Key Fields: Although fields are optional, returning at least first_name and email is highly recommended for a personalized experience.