Getting Started

Sign up/log in and create a site in Dashboard
Get API Key and embed code
Paste into your site's <head> and optionally set visitor id/nickname

1. Embed Script

Place the following code in your website's <head>, replace with your actual domain and API KEY:

<script>
// Optional: Set visitor ID and nickname before loading script, for deduplication and displaywindow.OCS = {
  externalId: 'user_12345', // Fixed ID for the same user  nickname: 'John Doe'        // Will be displayed in window title/backend};
</script>
<script>(function(){
  var s=document.createElement('script');
  s.src='http://www.chatgonow.com/api/widget.js?key=YOUR_API_KEY';
  s.async=true;document.head.appendChild(s);
})();</script>

2. Theme & Style

You can customize in "My Sites":

Primary color, text color, header colors
Theme variants: Classic / Minimal / Bubble
Button position: bottom-left / bottom-right
Welcome text

3. Image upload & text messages

Visitor window supports sending text and images (png/jpg/gif). Images are securely uploaded to the platform and displayed in both backend and visitor side.

4. Rate limiting

You can set maximum messages per minute in "My Sites" to prevent spam. Exceeding the threshold will show "sending too frequently".

Chat API rate limit: fetch and reply share the same per-minute threshold but are counted separately.

5. Visitor deduplication

The system prioritizes using window.OCS.externalId for deduplication. If not set, it automatically generates and reuses an ocs_external_id in local Cookie/LocalStorage. Same externalId under the same site is treated as the same visitor.

6. Operator console

After logging in, enter the online chat console from "My Sites" to view visitor sessions in real-time, send text/images, and check unread notifications.

7. Open API

We provide simple and easy-to-use APIs to help you integrate chat data into your internal systems.

Last 50 messages (by site): GET /api/chat_api.php?action=get_recent_messages&key=CHAT_API_KEY
Reply as agent: POST /api/chat_api.php?action=reply_as_agent&key=CHAT_API_KEY
Important: There are two API Key types:

Widget API Key：Used to embed widget on customer sites
Chat API Key：Used for Open API (fetch/reply)

API Field Description

Get Messages API Response Fields:

Field Name	Type	Description
`conversation_id`	string	Conversation ID to identify the chat session
`sender_type`	string	Sender type: visitor or agent
`sender_user_id`	string	Sender ID: random for visitors, API key for agents
`message_type`	string	Message type: text or image
`content`	string	Message content, empty for image messages
`image_url`	string\|null	Image URL, only for image messages
`created_at`	string	Message creation time (format: YYYY-MM-DD HH:MM:SS)

Agent Reply API Request Fields:

Field Name	Type	Required	Description
`conversation_id`	integer	✓	Conversation ID
`content`	string	✓*	Reply content (either this or image_base64)
`image_base64`	string	✓*	Base64 encoded image (either this or content)
`agent_name`	string	-	Agent name, defaults to "Agent"

* means either content or image_base64 must be provided

Example

1. Get Recent Messages

Request Example

curl "http://www.chatgonow.com/api/chat_api.php?action=get_recent_messages&key=CHAT_API_KEY"

Success Response Example:

Response Data

{
  "success": true,
  "data": [
    {
      "conversation_id": "123",
      "sender_type": "visitor",
      "sender_user_id": "visitor_abc123",
      "message_type": "text",
      "content": "Hello, I would like to inquire about product pricing",
      "image_url": null,
      "created_at": "2024-01-15 14:30:25"
    },
    {
      "conversation_id": "123",
      "sender_type": "agent",
      "sender_user_id": "chat_xyz789",
      "message_type": "text",
      "content": "Hello! I'm happy to help you. Which product pricing would you like to know about?",
      "image_url": null,
      "created_at": "2024-01-15 14:31:10"
    },
    {
      "conversation_id": "124",
      "sender_type": "visitor",
      "sender_user_id": "visitor_def456",
      "message_type": "image",
      "content": "",
      "image_url": "/uploads/chat_images/visitor_20240115_143200.jpg",
      "created_at": "2024-01-15 14:32:00"
    }
  ]
}

Error Response Examples:

Error Responses

// Missing API Key{
  "success": false,
  "message": "missing key"
}

// Invalid API Key{
  "success": false,
  "message": "invalid key"
}

// Too many requests{
  "success": false,
  "message": "too many requests, wait 3s"
}

2. Agent Reply

Request Example

curl -X POST "http://www.chatgonow.com/api/chat_api.php?action=reply_as_agent&key=CHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"conversation_id":123,"content":"Hello, we have received your message","agent_name":"Agent Wang"}'

Success Response Example:

Response Data

{
  "success": true
}

Error Response Examples:

Error Responses

// Missing API Key{
  "success": false,
  "message": "missing key"
}

// Invalid API Key{
  "success": false,
  "message": "invalid key"
}

// Conversation not found{
  "success": false,
  "message": "conversation not found"
}

// Empty content{
  "success": false,
  "message": "empty content"
}