> This page is for Referencia de la API.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://signalcore.ai/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://signalcore.ai/docs/_mcp/server.

# Operator

POST https://signalcore.ai/v1/conversations/{conversation_id}/operator
Content-Type: application/json

A person of the business writes to the person on the channel (`doors.channels`):
delivered as theirs, and the conversation theirs (the agent quiet) until it is given back,
or they have been quiet in it for the channel's `auto_release_after_h`.

Reference: https://signalcore.ai/docs/referencia/conversaciones/operator

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Request

### Path parameters

- `conversation_id` (string, required)

### Body (application/json)

This endpoint expects an object.

- `text` (string, optional, default: )
- `files` (list of string, optional, default: [])

## Response

### 201

Successful Response

- `id` (string, required)
- `role` (enum, required)
  - Allowed values: `user`, `assistant`
- `text` (string, required)
- `action` (map from string to any, required, nullable)
- `steps` (list of StepOut, required)
- `created_at` (datetime, required)
- `files` (list of FileRef, optional, default: [])
- `author` (enum, optional, nullable)
  - Allowed values: `contact`, `agent`, `operator`
- `delivery` (enum, optional, nullable)
  - Allowed values: `queued`, `sent`, `delivered`, `read`, `failed`
- `delivery_error` (string, optional, nullable)
- `pieces` (list of string, optional, nullable)
- `sent_parts` (integer, optional, nullable)
- `voice` (FileRef, optional, nullable) — A file of the conversation as a message shows it; its bytes are at `GET /conversations/{id}/files/{file_id}`.
- `heard` (string, optional, nullable)
- `decision` (AppSchemasDecisionOut, optional, nullable) — What was decided of a contact's message (`handlers`): by the channel's filter, the agent answers it or not this time (`skip`); by the agent's own handlers (`@sc.on`), it answers, or the conversation goes to a person (`hold`) or to nobody (`ignore`); `deciding` while they go.

## Errors

### 422 Conversations Operator Request Unprocessable Entity Error

Validation Error

- `detail` (list of ValidationError, optional)

## Types

### StepOut

An action a reply called: what, how it went, and what it drew.

- `id` (string, required)
- `action` (string, required)
- `state` (enum, required)
  - Allowed values: `running`, `waiting`, `done`, `failed`
- `output` (string, required, nullable)
- `surface` (map from string to any, required, nullable)
- `awaits` (boolean, required)
- `request` (map from string to any, required, nullable)
- `app` (StepApp, optional, nullable) — The connected app an action belongs to, as its step shows it: its name and its logo (an https address; none when the provider has none).

### FileRef

A file of the conversation as a message shows it; its bytes are at `GET /conversations/{id}/files/{file_id}`.

- `id` (string, required)
- `name` (string, required)
- `media_type` (string, required)
- `size` (integer, required)

### AppSchemasDecisionOut

What was decided of a contact's message (`handlers`): by the channel's filter, the agent answers it or not this time (`skip`); by the agent's own handlers (`@sc.on`), it answers, or the conversation goes to a person (`hold`) or to nobody (`ignore`); `deciding` while they go.

- `kind` (enum, required)
  - Allowed values: `deciding`, `answer`, `skip`, `hold`, `ignore`
- `reason` (string, required, nullable)
- `automation` (string, required, nullable)
- `title` (string, required, nullable)
- `run_id` (string, required, nullable)

### ValidationError

- `loc` (list of ValidationErrorLocItem, required)
- `msg` (string, required)
- `type` (string, required)
- `input` (any, optional)
- `ctx` (map from string to any, optional)

### StepApp

The connected app an action belongs to, as its step shows it: its name and its logo (an https address; none when the provider has none).

- `name` (string, required)
- `icon` (string, optional, nullable)

### ValidationErrorLocItem

## Examples

**Request**

```json
{}
```

**Response**

```json
{
  "id": "id",
  "role": "user",
  "text": "text",
  "action": {
    "key": "value"
  },
  "steps": [
    {
      "id": "id",
      "action": "action",
      "state": "running",
      "output": "output",
      "surface": {
        "key": "value"
      },
      "awaits": true,
      "request": {
        "key": "value"
      },
      "app": {
        "name": "name"
      }
    }
  ],
  "created_at": "2024-01-15T09:30:00Z",
  "files": [
    {
      "id": "id",
      "name": "name",
      "media_type": "media_type",
      "size": 1
    }
  ],
  "author": "contact",
  "delivery": "queued",
  "delivery_error": "delivery_error",
  "pieces": [
    "pieces"
  ],
  "sent_parts": 1,
  "voice": {
    "id": "id",
    "name": "name",
    "media_type": "media_type",
    "size": 1
  },
  "heard": "heard",
  "decision": {
    "kind": "deciding",
    "reason": "reason",
    "automation": "automation",
    "title": "title",
    "run_id": "run_id"
  }
}
```

**SDK Code**

```python
import requests

url = "https://signalcore.ai/v1/conversations/conversation_id/operator"

payload = {}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```