Skip to main content

Deepdesk CX Assistants — API and Evaluation Guide

Intro​

Deepdesk CX Assistants let you manage and evaluate GenAI-powered assistants integrated with your CX platform. You can:

  • Monitor performance — Track effectiveness and efficiency with analytics and reporting
  • Optimize interactions — Use real-time data and feedback to improve AI–customer interactions
  • Customize responses — Tailor responses to business needs and customer expectations
  • Integrate seamlessly — Connect with existing CX platforms and tools
  • Ensure compliance — Use built-in compliance features and updates

APIs​

Two APIs are available under the same service:

  • Assistants Admin API — CRUD for managing assistants and related config (APIs, tools)
  • Assistants Evaluation API — Execute and test an assistant (evaluate endpoint)

OpenAPI/Swagger docs for your account are available at https://<account>.deepdesk.com/api/v2/docs (or your environment’s API docs URL).

Authentication​

Use the OAuth2 Client Credentials flow to obtain an access token.

Endpoint​

  • URL: https://<account>.deepdesk.com/oauth/token/
  • Method: POST
  • Content-Type: application/x-www-form-urlencoded

Request parameters​

ParameterValue
grant_typeclient_credentials
client_idYour client ID
client_secretYour client secret
scopeassistants:read assistants:write

Example request​

curl -X POST https://<account>.deepdesk.com/oauth/token/ \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=your-client-id" \
  -d "client_secret=your-client-secret" \
  -d "scope=assistants:read"

Example response​

{
  "access_token": "your-access-token",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "assistants:read"
}

Using the access token​

Send the token in the Authorization header:

curl -X POST "https://<account>.deepdesk.com/api/v2/assistants/<assistant-code>/evaluate?conversation_id=<id>" \
  -H "Authorization: Bearer <your-access-token>" \
  -H "Content-Type: application/json" \
  -d '{"input": {"foo": "bar"}}'
Scopes
  • assistants:write — Required for creating or updating assistants
  • assistants:read — Required for evaluating assistants

Admin API examples​

Create an assistant​

Endpoint: POST /apis/admin/assistants/

curl -X POST "https://<account>.deepdesk.com/apis/admin/assistants/" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
  "code": "my-assistant",
  "name": "My Assistant",
  "instructions": "You are a helpful assistant that summarizes a conversation",
  "model": "gpt-4o",
  "response_format_json": true,
  "temperature": 0.0,
  "top_p": 1.0,
  "tools": [],
  "include_conversation_transcript": true,
  "include_conversation_metadata": true
}'

Response: JSON object with the created assistant (id, code, name, instructions, model, tools, etc.).

Get existing assistants​

Endpoint: GET /apis/admin/assistants/

curl -X GET "https://<account>.deepdesk.com/apis/admin/assistants/" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <token>"

Response: Array of assistant objects.

Partially update an assistant​

Endpoint: PATCH /apis/admin/assistants/{code}/

curl -X PATCH "https://<account>.deepdesk.com/apis/admin/assistants/my-assistant/" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"include_conversation_metadata": false}'

Response: Updated assistant object.

Evaluation​

To evaluate an assistant you need:

  • The assistant code
  • Optionally: conversation_id (CX platform conversation/thread/session ID; e.g. RingCentral content thread ID like 667d72034007c600072f766a)

Input​

You can pass additional input in the request body; it is included in the assistant’s prompt:

{
  "input": {
    "media_type": "chat"
  }
}

Example request:

curl -X POST "https://<account>.deepdesk.com/api/v2/assistants/my-assistant/evaluate?conversation_id=<id>" \
  -H "Authorization: Bearer <your-access-token>" \
  -H "Content-Type: application/json" \
  -d '{"input": {"media_type": "chat"}}'

Output​

The response returns the LLM output as text:

{
  "output": "Hello, world!"
}

Tools​

Assistants can be configured with tools. The model decides when to call a tool based on the user’s request. Examples:

  • API calls — Post or retrieve data from internal or external APIs (credentials configured securely, not in the LLM prompt)
  • Python execution — Run Python for calculations, data analysis, etc.
  • Assistants — Call other assistants for specialized tasks (they can have their own tools)
  • Web browsing — Browse sites and retrieve real-time information
  • Memory storage — Remember information across sessions

For a full list and parameters, see Assistant tools and how to use them.

Use case: Routing​

Example: a routing assistant that categorizes the conversation, validates the category, and updates the category via the CX platform API.

1. Create an API (CX platform)​

curl -X 'POST' \
  'https://<account>.deepdesk.com/apis/admin/assistants/apis/' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "code": "mock-cx-platform",
  "url": "https://mock-cx-platform.free.beeceptor.com",
  "headers": "{\"some-header\": \"some-value\"}"
}'

Keeping the API config separate from the assistant secures credentials and keeps them out of the prompt. You can use a mock service (e.g. Beeceptor) to inspect requests.

2. List tools and get call_api ID​

curl -X 'GET' \
  'https://<account>.deepdesk.com/apis/admin/assistants/tools/' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <your-access-token>'

Find the call_api tool in the response (e.g. "id": 12). It has parameters: api_code, path, method, and optionally headers, payload.

3. Create the routing assistant​

Instructions should tell the assistant to call call_api with the correct api_code, path, and method after determining the category. Example instructions:

Categorize the conversations based on the provided categories.

If the conversation does not match any of the topics below, assign the category_id "65fdaa3d6ff9c000071fa8ab".

When the category has been determined, call the "call_api" function:
- api_code: mock-cx-platform
- path: /some-path/categories?thread_category_ids[]={new_category_id}
- method: PUT

Create the assistant with that instruction and the tool ID (e.g. "tools": [12]) via POST /apis/admin/assistants/.

4. Evaluate​

curl -X 'POST' \
  'https://<account>.deepdesk.com/api/v2/assistants/routing-assistant/evaluate?conversation_id=669fbd2936688700080849f5' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{"input": {}}'
tip

With include_conversation_transcript enabled and conversation_id in the query, the assistant receives the transcript automatically. You can also pass the transcript in the request body. The input field is for additional parameters only.

You can verify the outgoing API call in your mock service (e.g. Beeceptor). The assistant response will look like:

{
  "output": "The conversation has been categorized under \"Change subscription\" and the category has been updated successfully. How else can I assist you today?"
}

Code example (Python)​

import requests

# OAuth client credentials
client_id = '<client-id>'
client_secret = '<client-secret>'
scope = 'assistants:read'

# Get access token
auth_url = 'https://<account>.deepdesk.com/oauth/token/'
auth_data = {
    'grant_type': 'client_credentials',
    'client_id': client_id,
    'client_secret': client_secret,
    'scope': scope
}

auth_response = requests.post(auth_url, data=auth_data)
auth_response.raise_for_status()
access_token = auth_response.json().get('access_token')

# Evaluate assistant
url = 'https://<account>.deepdesk.com/api/v2/assistants/my-assistant/evaluate'
headers = {
    'accept': 'application/json',
    'Content-Type': 'application/json',
    'Authorization': f'Bearer {access_token}'
}
data = {"input": {"text": "Hello world!"}}

response = requests.post(url, headers=headers, json=data)
print(response.status_code)
print(response.json())

See also​