Sync Conversation API

The sync-conversation endpoint allows you to create, update, or delete conversations. This endpoint automatically handles conversation creation and can optionally create greeting messages based on your domain configuration.

Endpoint

POST /sync-conversation

Authentication

This endpoint requires authentication using the auth token obtained from generate-client-auth-token.

Include the token in the Authorization header:

Authorization: Bearer {auth_token}

Request Headers

Header	Required	Description
domain	Yes	The domain/group_name identifier for your tenant
Authorization	Yes	Bearer token from generate-client-auth-token
Content-Type	Yes	Must be application/json

Request Body

{
  user_id: string;           // Required: User identifier
  conversation_id?: string;  // Optional: Specific conversation ID (if not provided, a new one is created)
  context?: {                // Optional: User context and metadata
    first_name?: string;
    last_name?: string;
    // ... any custom fields
  };
  is_delete?: boolean;       // Optional: Set to true to delete the conversation
}

Request Parameters

user_id (required)

• Type: string
• Description: Unique identifier for the user associated with the conversation
• Example: "user-123" or "550e8400-e29b-41d4-a716-446655440000"

conversation_id (optional)

• Type: string
• Description: Specific conversation ID to use. If not provided, a new conversation ID is automatically generated
• Example: "conv-abc-123"

context (optional)

• Type: object
• Description: User context and metadata to store with the conversation. This can include user information and custom fields
• Example:

  {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "custom_field": "custom_value"
  }

• Note: If first_name is provided in context, it will be used to personalize greeting messages (if configured)

is_delete (optional)

• Type: boolean
• Description: Set to true to delete the conversation. When deleting, conversation_id must be provided
• Default: false

Success Response

Creating/Updating a Conversation

Status Code: 200

{
  statusCode: 200;
  data: {
    conversation_id: string;      // Unique conversation identifier
    domain: string;               // Domain/group_name
    channel: string;              // Channel type (e.g., "CHAT")
    user_id: string;             // User identifier
    context?: object;            // Conversation context (if provided)
    created_at: string;          // ISO timestamp
    updated_at: string;          // ISO timestamp
    // ... other conversation fields
  };
  message: "OKAY";
}

Deleting a Conversation

Status Code: 200

{
  statusCode: 200;
  data: {
  }
  message: "OKAY";
}

Error Responses

Missing Required Fields (435)

{
  statusCode: 435;
  data: {
  }
  message: "Missing required fields: user_id";
}

Unauthorized (403)

{
  statusCode: 403;
  data: {
  }
  message: "UNAUTHORIZED";
}

Causes:

• Missing or invalid Authorization header
• Expired or invalid auth token
• Missing domain header

Not Found (437)

{
  statusCode: 437;
  data: {
  }
  message: "ENTRY_NOT_FOUND";
}

Causes:

• Attempting to delete a conversation that doesn't exist
• Invalid conversation_id provided

Server Fault (500)

{
  statusCode: 500;
  data: {
  }
  message: "SERVER_FAULT";
}

Example Requests

Example 1: Create a New Conversation

This example shows the complete flow from authentication to conversation creation:

# Step 1: Generate auth token
curl -X POST https://api.example.com/generate-client-auth-token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your-client-id",
    "client_secret": "your-client-secret",
    "fingerprint": "device-fingerprint-123",
    "user": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com",
      "group_name": "my-domain"
    }
  }'

# Response:
# {
#   "statusCode": 200,
#   "data": {
#     "auth_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
#   },
#   "message": "OKAY"
# }

# Step 2: Create conversation using the auth token
curl -X POST https://api.example.com/sync-conversation \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "domain: my-domain" \
  -d '{
    "user_id": "user-123",
    "context": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com"
    }
  }'

Response:

{
  "statusCode": 200,
  "data": {
    "conversation_id": "conv-abc-123-def-456",
    "domain": "my-domain",
    "channel": "CHAT",
    "user_id": "user-123",
    "context": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com"
    },
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  },
  "message": "OKAY"
}

Example 2: Create Conversation with Specific ID

curl -X POST https://api.example.com/sync-conversation \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {auth_token}" \
  -H "domain: my-domain" \
  -d '{
    "user_id": "user-123",
    "conversation_id": "my-custom-conv-id",
    "context": {
      "first_name": "Jane",
      "last_name": "Smith"
    }
  }'

Example 3: Update Conversation Context

curl -X POST https://api.example.com/sync-conversation \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {auth_token}" \
  -H "domain: my-domain" \
  -d '{
    "user_id": "user-123",
    "conversation_id": "conv-abc-123-def-456",
    "context": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com",
      "preferences": {
        "language": "en",
        "timezone": "America/New_York"
      }
    }
  }'

Example 4: Delete a Conversation

curl -X POST https://api.example.com/sync-conversation \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {auth_token}" \
  -H "domain: my-domain" \
  -d '{
    "is_delete": true,
    "conversation_id": "conv-abc-123-def-456"
  }'

Try It Out

API Configuration

Base URL

Authentication

Auth Token *Token obtained from the generate-client-auth-token endpoint

Domain *The domain/group_name identifier for your tenant

Conversation Details

User ID *Unique identifier for the user

Conversation IDOptional. If not provided, a new conversation ID will be generated

Delete ConversationWhen checked, conversation_id is required and the conversation will be deleted

Context (Optional)

First Name

Last Name

Email

User context and metadata. If first_name is provided, it will be used to personalize greeting messages (if configured).

Request Preview

{
  "user_id": ""
}

Integration Example

Here's a complete JavaScript/TypeScript example showing the full integration:

// Step 1: Generate auth token
async function generateAuthToken() {
  const response = await fetch(
    "https://api.example.com/generate-client-auth-token",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        client_id: "your-client-id",
        client_secret: "your-client-secret",
        fingerprint: "device-fingerprint-123",
        user: {
          first_name: "John",
          last_name: "Doe",
          email: "john.doe@example.com",
          group_name: "my-domain",
        },
      }),
    }
  );

  const result = await response.json();
  return result.data.auth_token;
}

// Step 2: Create conversation
async function createConversation(
  authToken: string,
  userId: string,
  context?: object
) {
  const response = await fetch("https://api.example.com/sync-conversation", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${authToken}`,
      domain: "my-domain",
    },
    body: JSON.stringify({
      user_id: userId,
      context: context,
    }),
  });

  const result = await response.json();

  if (result.statusCode !== 200) {
    throw new Error(`Failed to create conversation: ${result.message}`);
  }

  return result.data;
}

// Usage
async function main() {
  try {
    // Authenticate
    const authToken = await generateAuthToken();
    console.log("Auth token obtained:", authToken);

    // Create conversation
    const conversation = await createConversation(authToken, "user-123", {
      first_name: "John",
      last_name: "Doe",
      email: "john.doe@example.com",
    });

    console.log("Conversation created:", conversation.conversation_id);
  } catch (error) {
    console.error("Error:", error);
  }
}

Behavior Notes

Greeting Messages

If your domain has a greeting message configured:

• A greeting message is automatically created as the first message in the conversation
• If context.first_name is provided, it will be used to personalize the greeting (replacing $$USER_NAME$$ placeholders)
• The greeting message is created asynchronously and may not appear immediately

Context Updates

• When context is provided, it's merged with any existing context
• Context updates happen asynchronously for better performance
• The response may return before context updates are fully persisted

Conversation ID Generation

• If conversation_id is not provided, a unique ID is automatically generated
• The generated ID format may vary but is guaranteed to be unique
• You can use the returned conversation_id for subsequent API calls

Related Documentation

• Conversations Overview - Learn about conversation concepts
• Client Credentials API - Authentication endpoint
• API Guidelines - General API response formats and error codes