Skip to main content

​
Overview

Socket.IO enables real-time bidirectional communication between your application and the Helpdesk system. This allows for instant messaging, live notifications, and seamless customer support experiences.

​
Connection

​
Authentication

Connect to the Socket.IO server using your API key: 
const API_BASE_URL = '{api_base_url}';
const socket = io(`${API_BASE_URL}/helpdesk?token_source=api&token=YOUR_API_KEY`);

​
Connection Response

Upon successful connection, you’ll receive a response with this schema: 
{
  "status_code": 200,
  "sid": "session_identifier",
  "message": "Connected successfully",
  "data": {}
}
If authentication fails, the connection will be refused with status_code 400 or 401.

​
Event Flow

The typical conversation flow involves these key events:
1

Connect

Establish authenticated connection to the server
2

Support

Send and receive messages between customer and AI/agent
3

Mark Read

Update read status for better user experience
4

Close Support

End conversations when issues are resolved
5

Review

Collect customer feedback after conversation ends

​
Events Reference

​
Support Event

The primary event for sending and receiving messages. Event Name: support

​
Request Schema

​
session_id
string
required
Unique identifier for the customer session
​
message
string
required
The message content to send
​
attachment
boolean
required
Whether this message includes an attachment
​
ticket_chat_id
string
Conversation ID. Use null for new conversations

​
Example Request

socket.emit('support', {
  session_id: 'customer_123',
  message: 'Hello, I need help with my order',
  attachment: false,
  ticket_chat_id: null // Creates new conversation
});

​
Response Schema

​
status_code
integer
HTTP status code (200 for success)
​
sid
string
Session identifier
​
message
string
Status message
​
data
object
Response data containing the message details
Data Object:
​
message
string
The response message content
​
ticket_chat_id
string
Conversation identifier (new for first message)
​
sender
string
Response sender: "sate" or "agent"
​
attachment
boolean
Whether the response includes an attachment
​
attachment_metadata
object
Attachment details (if applicable)
​
close_support
boolean
Whether AI suggests closing the conversation
​
closed_support
boolean
Whether the conversation is actually closed
​
date_created
string
ISO timestamp of message creation
​
date_updated
string
ISO timestamp of last update

​
Example Response

socket.on('support', (response) => {
  console.log(response);
  // {
  //   "status_code": 200,
  //   "sid": "socket_session_id",
  //   "message": "Message sent successfully",
  //   "data": {
  //     "message": "I'd be happy to help you with your order. Could you provide your order number?",
  //     "ticket_chat_id": "conv_abc123",
  //     "sender": "sate",
  //     "attachment": false,
  //     "attachment_metadata": null,
  //     "close_support": false,
  //     "closed_support": false,
  //     "date_created": "2024-01-15T10:31:00Z",
  //     "date_updated": "2024-01-15T10:31:00Z"
  //   }
  // }
});

​
Important Notes

  • New Conversations: Set ticket_chat_id to null for the first message. The response will include the new conversation ID.
  • Continuing Conversations: Use the ticket_chat_id from previous responses to continue the same conversation.
  • Conversation Limit: Each customer can have a maximum of 3 open conversations.
  • Attachments: Only available when responder is "agent". SATE responses cannot include attachments.

​
Mark Conversation Read

Update the read status for better user experience and notifications. Event Name: mark_conversation_read

​
Request Schema

​
ticket_chat_id
string
required
The conversation identifier to mark as read
​
entity
string
required
Who is marking it as read. Use "customer"

​
Example Request

socket.emit('mark_conversation_read', {
  ticket_chat_id: 'conv_abc123',
  entity: 'customer'
});

​
Response Schema

{
  "status_code": 200,
  "sid": "socket_session_id",
  "message": "Marked as read",
  "data": {}
}

​
Enter Support

Notify when a customer enters a conversation (optional for AI conversations). Event Name: enter_support

​
Request Schema

​
ticket_chat_id
string
required
The conversation identifier the customer is entering

​
Example Request

socket.emit('enter_support', {
  ticket_chat_id: 'conv_abc123'
});

​
Response Schema

{
  "status_code": 200,
  "sid": "socket_session_id",
  "message": "Entered support conversation",
  "data": {}
}

​
Close Support

End a conversation when the issue is resolved. Event Name: close_support
Use this event only after Sate indicates closure by setting close_support: true in a support response, and the customer confirms they want to end the conversation.

​
Request Schema

​
ticket_chat_id
string
required
The conversation identifier to close

​
Example Request

socket.emit('close_support', {
  ticket_chat_id: 'conv_abc123'
});

​
Response Schema

The response confirms the conversation is closed: 
{
  "status_code": 200,
  "sid": "socket_session_id",
  "message": "Support conversation closed",
  "data": {
    "message": "Thank you for using our support. Your conversation has been closed.",
    "ticket_chat_id": "conv_abc123",
    "sender": "sate",
    "attachment": false,
    "attachment_metadata": null,
    "close_support": true,
    "closed_support": true,
    "date_created": "2024-01-15T12:00:00Z",
    "date_updated": "2024-01-15T12:00:00Z"
  }
}

​
Review Support

Collect customer feedback after a conversation ends. Event Name: review_support

​
Request Schema

​
ticket_chat_id
string
required
The conversation identifier to review
​
review
string
Optional customer feedback text
​
rating
integer
required
Customer rating from 1 to 5

​
Example Request

socket.emit('review_support', {
  ticket_chat_id: 'conv_abc123',
  review: 'Great service, very helpful!',
  rating: 5
});

​
Response Schema

{
  "status_code": 200,
  "sid": "socket_session_id",
  "message": "Review submitted successfully",
  "data": {}
}

​
Implementation Example

Here’s a complete example showing the event flow: 
const API_BASE_URL = '{api_base_url}';
const socket = io(`${API_BASE_URL}/helpdesk?token_source=api&token=${API_KEY}`);

// Handle connection
socket.on('connect', () => {
  console.log('Connected to helpdesk');
});

// Send customer message
function sendMessage(sessionId, message, conversationId = null) {
  socket.emit('support', {
    session_id: sessionId,
    message: message,
    attachment: false,
    ticket_chat_id: conversationId
  });
}

// Listen for responses
socket.on('support', (response) => {
  if (response.status_code === 200) {
    const { data } = response;
    
    // Display the response message
    displayMessage(data.message, data.sender);
    
    // Check if AI suggests closing
    if (data.close_support && !data.closed_support) {
      showCloseConfirmation(data.ticket_chat_id);
    }
    
    // Mark as read
    socket.emit('mark_conversation_read', {
      ticket_chat_id: data.ticket_chat_id,
      entity: 'customer'
    });
  }
});

// Handle conversation closure
function closeConversation(conversationId) {
  socket.emit('close_support', {
    ticket_chat_id: conversationId
  });
}

// Submit review
function submitReview(conversationId, rating, feedback) {
  socket.emit('review_support', {
    ticket_chat_id: conversationId,
    rating: rating,
    review: feedback
  });
}

​
Next Steps