Skip to main content

Agents API

List All Agents

tenant_id
string
required
The ID of the tenant
curl -X GET \
  'https://a.messageflow.ai/api/v1/agents?tenant_id=123' \
  -H 'Authorization: Bearer YOUR_AUTH_TOKEN'
[
  {
    "id": 1,
    "name": "Example Agent",
    "number": "t123abc456",
    "description": "A sample agent"
  }
]

Get Agent Details

id
string
required
The ID of the agent
tenant_id
string
required
The ID of the tenant
curl -X GET \
  'https://a.messageflow.ai/api/v1/agents/1?tenant_id=123' \
  -H 'Authorization: Bearer YOUR_AUTH_TOKEN'
{
  "id": 1,
  "name": "Example Agent",
  "number": "t123abc456",
  "description": "A sample agent",
  "configuration": {
    "name": "Example Agent",
    "description": "A sample agent",
    "prompt": [
      {
        "id": 1,
        "name": "Initial Prompt",
        "prompt": "Your prompt text here",
        "initial_response": "Initial response text",
        "voice": "echo",
        "function_ids": [],
        "tools": [],
        "actions": {},
        "integration": {
          "id": 1,
          "name": "Example Integration",
          "server": "https://api.example.com",
          "bearer_token": "your-token"
        }
      }
    ]
  }
}

Create New Agent

tenant_id
string
required
The ID of the tenant
agent[name]
string
required
Name of the agent
agent[description]
string
Description of the agent
agent[configuration]
object
Configuration for the agent
curl -X POST \
  'https://a.messageflow.ai/api/v1/agents?tenant_id=123' \
  -H 'Authorization: Bearer YOUR_AUTH_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "agent": {
      "name": "New Agent",
      "description": "A new agent",
      "configuration": {
        "prompt": [
          {
            "name": "Initial Prompt",
            "prompt": "Your prompt text here",
            "initial_response": "Initial response text",
            "voice": "echo"
          }
        ]
      }
    }
  }'
{
  "id": 2,
  "name": "New Agent",
  "number": "t123def789",
  "description": "A new agent",
  "tenant_id": 123
}

Update Agent

id
string
required
The ID of the agent
tenant_id
string
required
The ID of the tenant
curl -X PUT \
  'https://a.messageflow.ai/api/v1/agents/1?tenant_id=123' \
  -H 'Authorization: Bearer YOUR_AUTH_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "agent": {
      "name": "Updated Agent",
      "description": "Updated description",
      "configuration": {
        "prompt": [
          {
            "name": "Updated Prompt",
            "prompt": "Updated prompt text",
            "initial_response": "Updated response text",
            "voice": "echo"
          }
        ]
      }
    }
  }'
{
  "id": 1,
  "name": "Updated Agent",
  "number": "t123abc456",
  "description": "Updated description",
  "configuration": {
    "name": "Updated Agent",
    "description": "Updated description",
    "prompt": [
      {
        "id": 1,
        "name": "Updated Prompt",
        "prompt": "Updated prompt text",
        "initial_response": "Updated response text",
        "voice": "echo",
        "function_ids": [],
        "tools": [],
        "actions": {},
        "integration": {
          "id": 1,
          "name": "Example Integration",
          "server": "https://api.example.com",
          "bearer_token": "your-token"
        }
      }
    ]
  }
}

Delete Agent

id
string
required
The ID of the agent
tenant_id
string
required
The ID of the tenant
curl -X DELETE \
  'https://a.messageflow.ai/api/v1/agents/1?tenant_id=123' \
  -H 'Authorization: Bearer YOUR_AUTH_TOKEN'
{
  "status": "Agent 1 deleted"
}

HTTP Status Codes

  • 200: Success
  • 201: Created
  • 400: Bad Request
  • 401: Unauthorized
  • 404: Not Found
  • 422: Unprocessable Entity

Agent Configuration

The agent configuration includes:
  • Name and description
  • Prompt configuration with:
    • Initial prompt text
    • Initial response
    • Voice settings
    • Function IDs
    • Tools
    • Actions
    • Integration settings

Voice Options

Available voice options:
  • alloy
  • ash
  • ballad
  • coral
  • echo
  • sage
  • shimmer
  • verse