Create Persona

Create a new customer behavior profile for testing scenarios.

Personas help create realistic and varied interactions for comprehensive agent evaluation.

Request

curl -X POST "https://api.chanl.ai/api/v1/workspaces/ws_123/personas" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Frustrated Customer",
    "language": "en",
    "prompt": "You are a frustrated customer who has been having issues with your service for weeks. You are impatient and want immediate resolution. Speak with an upset but not abusive tone.",
    "emotion": "frustrated",
    "difficulty": "hard",
    "backgroundNoise": "office",
    "tags": ["frustrated", "impatient", "support"]
  }'

const response = await fetch(`https://api.chanl.ai/api/v1/workspaces/${workspaceId}/personas`, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + accessToken,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Frustrated Customer',
    language: 'en',
    prompt: 'You are a frustrated customer who has been having issues with your service for weeks. You are impatient and want immediate resolution. Speak with an upset but not abusive tone.',
    emotion: 'frustrated',
    difficulty: 'hard',
    backgroundNoise: 'office',
    tags: ['frustrated', 'impatient', 'support']
  })
});

const { data } = await response.json();
console.log('New persona:', data.persona);

import requests

response = requests.post(
    f'https://api.chanl.ai/api/v1/workspaces/{workspace_id}/personas',
    headers={'Authorization': f'Bearer {access_token}'},
    json={
        'name': 'Frustrated Customer',
        'language': 'en',
        'prompt': 'You are a frustrated customer who has been having issues with your service for weeks. You are impatient and want immediate resolution. Speak with an upset but not abusive tone.',
        'emotion': 'frustrated',
        'difficulty': 'hard',
        'backgroundNoise': 'office',
        'tags': ['frustrated', 'impatient', 'support']
    }
)

persona = response.json()['data']['persona']

Response

{
  "success": true,
  "data": {
    "persona": {
      "id": "persona_789",
      "name": "Frustrated Customer",
      "language": "en",
      "prompt": "You are a frustrated customer who has been having issues with your service for weeks. You are impatient and want immediate resolution. Speak with an upset but not abusive tone.",
      "emotion": "frustrated",
      "difficulty": "hard",
      "backgroundNoise": "office",
      "tags": ["frustrated", "impatient", "support"],
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z",
      "created_by": {
        "id": "user_123",
        "name": "John Doe"
      }
    }
  }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid persona data",
    "details": {
      "name": "Name is required and must be unique within the workspace",
      "language": "Language must be a valid ISO 639-1 code"
    }
  }
}

Required Fields

namestringrequired

Descriptive name for the persona (must be unique within workspace)

languagestringrequired

Language code in ISO 639-1 format (e.g., "en", "es", "fr")

promptstringrequired

Detailed behavioral description and instructions for the persona

Optional Fields

emotionstring

Emotional state: frustrated, happy, confused, neutral, angry, excited, etc.

difficultystring

Interaction difficulty level: easy, medium, hard

backgroundNoisestring

Audio environment: none, office, street, cafe, custom

tagsarray

Array of categorization tags for filtering and organization

Persona Examples

{
  "name": "Confused Customer",
  "language": "en",
  "prompt": "You are a customer who doesn't understand technology very well. You need help but have trouble explaining your issue clearly. Ask lots of questions and need things explained simply.",
  "emotion": "confused",
  "difficulty": "medium",
  "backgroundNoise": "none",
  "tags": ["confused", "support", "technical"]
}

{
  "name": "Price-Sensitive Buyer",
  "language": "en",
  "prompt": "You are interested in the product but very concerned about price. You want to understand value and ask about discounts, cheaper alternatives, and payment plans.",
  "emotion": "cautious",
  "difficulty": "medium",
  "backgroundNoise": "office",
  "tags": ["sales", "price-sensitive", "cautious"]
}

{
  "name": "Tech-Savvy User",
  "language": "en",
  "prompt": "You are technically knowledgeable and have already tried basic troubleshooting. You provide detailed information and prefer technical explanations.",
  "emotion": "analytical",
  "difficulty": "easy",
  "backgroundNoise": "none",
  "tags": ["technical", "advanced", "analytical"]
}

Best Practices

Create personas based on real customer interactions and feedback data

Use specific, actionable behavioral descriptions
Include relevant emotional context that affects conversation tone
Test personas across different scenarios before production use
Tag personas consistently for easy filtering and organization
Keep prompts focused but detailed enough for consistent behavior
Avoid contradictory instructions within a single persona

Required Fields

Optional Fields

Persona Examples

Best Practices

On this page