---

title: "ServiceAI Platform API Documentation" version: "v1.0.0" base_url: "https://api.serviceai.com/v1" api_version: "1.0" last_updated: "2024-03-15" status: "Stable"

ServiceAI Platform API Documentation

Overview

The ServiceAI Platform API provides programmatic access to our AI-powered customer service platform. This RESTful API enables developers to integrate ServiceAI's capabilities into their applications, manage customer interactions, and access analytics data.

Base URL

https://api.serviceai.com/v1

API Versioning

• Current Version: v1.0.0
• Release Date: March 15, 2024
• Deprecation Policy: 12 months notice before EOL

Authentication

API Keys

All API requests must include an API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Obtaining API Keys

1. Log in to the ServiceAI Dashboard
2. Navigate to Settings > API Keys
3. Click "Generate New Key"
4. Store the key securely (it won't be shown again)

API Key Types

• Test Keys: Prefix

  sk_test_

• Production Keys: Prefix

  sk_prod_

• Read-only Keys: Prefix

  sk_read_

Rate Limiting

Limits

Headers

• X-RateLimit-Limit

  : Total requests allowed per window

• X-RateLimit-Remaining

  : Remaining requests in current window

• X-RateLimit-Reset

  : Time until limit resets (Unix timestamp)

Handling Rate Limits

• Implement exponential backoff
• Cache responses when possible
• Monitor rate limit headers

API Endpoints

Conversations

Create Conversation

POST /conversations

Request Body

{
  "customer_id": "cust_123",
  "initial_message": "Hello, I need help with my order",
  "channel": "chat",
  "priority": "normal"
}

Response

{
  "conversation_id": "conv_abc123",
  "status": "active",
  "created_at": "2024-03-15T10:00:00Z",
  "customer": {
    "id": "cust_123",
    "name": "John Doe"
  }
}

List Conversations

GET /conversations

Query Parameters

• status

  : Filter by status (active, closed, pending)

• customer_id

  : Filter by customer

• limit

  : Number of records (default: 20, max: 100)

• offset

  : Pagination offset

Response

{
  "data": [
    {
      "conversation_id": "conv_abc123",
      "status": "active",
      "created_at": "2024-03-15T10:00:00Z",
      "customer": {
        "id": "cust_123",
        "name": "John Doe"
      }
    }
  ],
  "meta": {
    "total": 45,
    "limit": 20,
    "offset": 0
  }
}

Messages

Send Message

POST /conversations/{conversation_id}/messages

Request Body

{
  "content": "Your order #12345 has been shipped",
  "type": "text",
  "sender_type": "agent"
}

Response

{
  "message_id": "msg_xyz789",
  "conversation_id": "conv_abc123",
  "content": "Your order #12345 has been shipped",
  "type": "text",
  "sender_type": "agent",
  "sent_at": "2024-03-15T10:05:00Z"
}

Error Handling

Error Codes

Error Response Format

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid parameter: customer_id",
    "details": {
      "field": "customer_id",
      "reason": "must be a valid customer ID"
    }
  }
}

Data Models

Conversation Object

interface Conversation {
  conversation_id: string;
  customer_id: string;
  status: "active" | "closed" | "pending";
  created_at: string;
  updated_at: string;
  channel: "chat" | "email" | "voice";
  priority: "low" | "normal" | "high";
  metadata?: Record<string, any>;
}

Message Object

interface Message {
  message_id: string;
  conversation_id: string;
  content: string;
  type: "text" | "image" | "file";
  sender_type: "customer" | "agent" | "system";
  sent_at: string;
  metadata?: Record<string, any>;
}

Webhooks

Available Events

• conversation.created

• conversation.updated

• conversation.closed

• message.created

• message.updated

Webhook Format

{
  "event": "conversation.created",
  "created_at": "2024-03-15T10:00:00Z",
  "data": {
    "conversation_id": "conv_abc123",
    "customer_id": "cust_123",
    "status": "active"
  }
}

Webhook Security

1. Verify signature in

   X-ServiceAI-Signature

   header
2. Implement retry logic for failed deliveries
3. Respond with 2xx status code promptly

SDK Examples

Python

from serviceai import ServiceAI

client = ServiceAI("YOUR_API_KEY")

# Create conversation
conversation = client.conversations.create(
    customer_id="cust_123",
    initial_message="Hello, I need help"
)

# Send message
message = client.messages.create(
    conversation_id=conversation.id,
    content="How can I help you today?"
)

JavaScript

import { ServiceAI } from '@serviceai/sdk';

const client = new ServiceAI('YOUR_API_KEY');

// Create conversation
const conversation = await client.conversations.create({
  customer_id: 'cust_123',
  initial_message: 'Hello, I need help'
});

// Send message
const message = await client.messages.create({
  conversation_id: conversation.id,
  content: 'How can I help you today?'
});

Best Practices

Rate Limiting

1. Implement exponential backoff
2. Monitor rate limit headers
3. Cache responses when possible
4. Use bulk endpoints for batch operations

Security

1. Keep API keys secure
2. Use HTTPS for all requests
3. Implement webhook signature verification
4. Rotate API keys periodically

Performance

1. Use compression
2. Implement caching
3. Batch requests when possible
4. Monitor API usage

Changelog

v1.0.0 (2024-03-15)

• Initial API release
• Basic conversation management
• Message handling
• Webhook support

v0.9.0 (2024-02-15)

• Beta release
• Limited API access
• Testing and feedback

Support

Contact

• Email: api-support@serviceai.com
• Status Page: status.serviceai.com
• Documentation: docs.serviceai.com

Resources

1. API Reference
2. SDK Documentation
3. Sample Applications
4. Community Forums

---

Last Updated: March 15, 2024 Version: 1.0.0