Our API documentation provides all the tools and information you need to seamlessly integrate with our platform.
Serviceform Public API Documentation
Version: 1.0.1
Specification: OAS 3.0
Swagger / Base URL: https://link.serviceform.com
Overview
The Serviceform Public API provides access to various endpoints for managing flex spaces, leads, and chat histories. Below is a summary of key endpoints available for flex-related operations.
Swagger documentation can be found here: https://link.serviceform.com
Authorisation
To interact with these endpoints, an API key (sf-api-key) is required. Unauthorized requests will result in a 403 response status.
Media Type
Responses are provided in application/json format.
Flex-Related Endpoints
1. Get Spaces
Endpoint: GET /flex/spaces
Description: Retrieve a list of all spaces.
Parameters: None
Responses: some text
-200: Successful response with a JSON array of spaces.
-403: Request failed due to an invalid API key.
Example Response:{
{
"id": "string",
"name": "string",
"fields": [
{
"machine": "string",
"name": "string",
"id": "string",
"type": "string",
"options": [
{
"machine": "string",
"label": "string",
"value": "string"
}
]
}
]
}
2. Get Items for a Specific Space
- Endpoint: GET /flex/spaces/{spaceId}/items
- Description: Retrieve items for a specific space identified by {spaceId}.
- Parameters:
- spaceId (string, required): ID of the space.
- Responses:
- 200: Successful response with items for the specified space.
- 403: Unauthorized access due to an invalid API key.
- 404: Space not found.
- Example Response:
[{
"last_updater": "string",
"uid": "string",
"clientId": "string",
"created": "2024-08-30T05:48:46.195Z",
"id": "string",
"updated": "2024-08-30T05:48:46.195Z",
"uuid": "string",
"space_id": "string",
"primary_field": "string"
}]
3. Create a New Item in a Specific Space
- Endpoint: POST /flex/spaces/{spaceId}/items
- Description: Create a new item within a specified space.
- Parameters:
- spaceId (string, required): ID of the space.
- Request Body:
{"primary_field": "string"}
- Responses:
- 200: Successfully created the item.
- 403: Unauthorized access due to an invalid API key.
- 422: Bad request with missing or invalid data.
4. Get a Specific Item from a Space
- Endpoint: GET /flex/spaces/{spaceId}/items/{itemId}
- Description: Retrieve a specific item from a space using {spaceId} and {itemId}.
- Parameters:
- spaceId (string, required): ID of the space.
- itemId (string, required): ID of the item.
- Responses:
- 200: Successful response with the specified item.
- 403: Unauthorized access due to an invalid API key.
- 404: Item not found.
- Example Response:
{"last_updater": "string",
"uid": "string",
"clientId": "string",
"created": "2024-08-30T05:48:46.199Z",
"id": "string",
"updated": "2024-08-30T05:48:46.199Z",
"uuid": "string",
"space_id": "string",
"primary_field": "string"}
5. Update an Item in a Specific Space
- Endpoint: PUT /flex/spaces/{spaceId}/items/{itemId}
- Description: Update an item within a specific space.
- Parameters:
- spaceId (string, required): ID of the space.
- itemId (string, required): ID of the item.
- Request Body:
{"primary_field": "string"}
- Responses:
- 200: Successfully updated the item.
- 400: Bad request with missing or invalid data.
- 403: Unauthorized access due to an invalid API key.
- 404: Item not found.
- 422: Bad request with missing or invalid data.
6. Delete an Item from a Specific Space
- Endpoint: DELETE /flex/spaces/{spaceId}/items/{itemId}
- Description: Delete an item from a specific space.
- Parameters:
- spaceId (string, required): ID of the space.
- itemId (string, required): ID of the item.
- Responses:
- 200: Successfully deleted the item.
- 403: Unauthorized access due to an invalid API key.
- 404: Item not found.
7. Delete an Item from a Specific Space
- Endpoint: DELETE /flex/spaces/{spaceId}/items/{itemId}
- Description: Deletes an item from a specific space identified by the spaceId and itemId.
- Parameters:
- spaceId (string, required): ID of the space.
- itemId (string, required): ID of the item.
- Responses:
- 200 OK: Successfully deleted the item.
- 403 Forbidden: Unauthorized. The provided sf-api-key is invalid.
- 404 Not Found: The requested item was not found.
Leads endpoint
1. Get Leads
- Endpoint: GET /leads
- Description: Retrieves a list of leads.
- Parameters: None
- Responses:
- 200 OK: Successfully retrieved the leads.
{
"id": "string",
"page_url": "string",
"pid": "string",
"language": "string",
"source": "string",
"tools": [{ "tid": "string" }],
"tid": "string",
"sid": "string",
"duration": 0,
"uid": "string",
"pageviews": 0,
"pages": [{ "duration": 0, "referrer": "string", "website": "string" }],
"browser": "string",
"tokens": [{}],
"first_name": "string",
"email": "string",
"timestamp": "2024-08-30T05:48:46.202Z",
"tool_name": "string",
"os": "string",
"indexed": true,
"created": "2024-08-30T05:48:46.202Z",
"mobile": true,
"last_name": "string",
"history": [
{ "id": "string", "message": "string", "type": "string", "timestamp": 0 }
],
"referrer": "string",
"site": "string",
"phone": "string",
"name": "string",
"page": "string",
"referrer_url": "string",
"updated": "2024-08-30T05:48:46.202Z",
"space_id": "string"
}
- 401 Unauthorized: The provided sf-api-key is invalid.
Chat history
1. Get all chats
- Endpoint: POST /chats
- Description: Retrieves the chat history based on specified filters such as time range, user ID, and message details.
- Headers:
- sf-api-key: (string, required) Your API key for authentication.
- Parameters: None
- Request Body:
- Fields:
- startTime (string, optional): Start of the time range in ISO 8601 format.
- endTime (string, optional): End of the time range in ISO 8601 format.
- uid (string, optional): User ID to filter the chats.
- limit (integer, optional): Maximum number of chat records to return.
- showMessages (boolean, optional): Whether to include chat messages in the response.
- chatbot (boolean, optional): Filter chats to include only those with chatbot interactions.
- Example Request:
{
"startTime": "2024-08-30T05:48:46.204Z",
"endTime": "2024-08-30T05:48:46.204Z",
"uid": "user123",
"limit": 10,
"showMessages": true,
"chatbot": true
}
- Responses:
- 200 OK: Successfully retrieved the chat history.
[
{
"cid": "chat123",
"agentEmail": "agent@example.com",
"agentId": "agent123",
"agentName": "John Doe",
"agentJoinedTime": 1672531200,
"avgBetweenMsg": 30,
"business_phone": "+1234567890",
"phone": "+1234567890",
"first_name": "Jane",
"last_name": "Doe",
"name": "Jane Doe",
"fullUrl": "https://example.com/chat",
"lastLiveMsg": 1672531300,
"changed": 1672531400,
"lastMessage": "Thank you for your inquiry!",
"lastMessageTime": 1672531350,
"lastSender": "agent",
"leadSentTo": "sales@example.com",
"livechat": 1,
"livechatStarted": 1672531200,
"msgType": "text",
"regNo": "ABC123",
"session": "session123",
"sid": "site123",
"sitename": "Example Site",
"source": "website",
"team": "Support",
"uid": "user123",
"url": "/support/chat",
"history": [
{
"id": "msg1",
"message": "Hello, how can I help you?",
"type": "text",
"timestamp": 1672531250
},
{
"id": "msg2",
"message": "I have a question about your service.",
"type": "text",
"timestamp": 1672531280
}
]
}
]
- 403 Forbidden: Unauthorized. The provided sf-api-key is invalid.
2. Get chat statistics
- Endpoint: GET /statistics/chat
- Description: Retrieves chat-related statistics, including key performance indicators and aggregated data about chats.
- Headers:some text
- sf-api-key: (string, required) Your API key for authentication.
- Parameters:some text
- startTime (string, optional): Start of the time range in ISO 8601 format.
- endTime (string, optional): End of the time range in ISO 8601 format.
- metrics (array of strings, optional): List of specific metrics to retrieve.
- Responses:some text
- 200 OK: Successfully retrieved chat statistics.some text
{
"totalChats": 150,
"averageResponseTime": 45, // in seconds
"satisfactionScore": 4.5, // out of 5
"chatsByAgent": [
{
"agentId": "agent123",
"agentName": "John Doe",
"totalChats": 50,
"averageResponseTime": 30
},
{
"agentId": "agent124",
"agentName": "Jane Smith",
"totalChats": 100,
"averageResponseTime": 50
}
],
"chatsBySource": { "website": 120, "mobile": 30 },
"chatDurations": { "0-5 minutes": 60, "5-10 minutes": 40, "10+ minutes": 50 }
}
- 400 Bad Request: Invalid parameters or missing required data.
- 403 Forbidden: Unauthorized. The provided sf-api-key is invalid.
This documentation provides a comprehensive overview of the /chats and /statistics/chat endpoints, including their functionalities, parameters, request structures, and response formats. If you need further details or have additional requests, feel free to ask!
%20-%20Copy.png)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
