Public API

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.
    • Example Response:

{  “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.
    • Example Response:

[  {    “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
    • Example Response:

{ “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!

‍