Calls

Management of video calls. Includes listing, details, assignment, start, completion, and file uploads.

Endpoints

Method	Endpoint	Description	Minimum Role
`GET`	`/api/v1/calls`	List calls	`attendant`
`GET`	`/api/v1/calls/:id`	Call details	`attendant`
`POST`	`/api/v1/calls/:id/assign`	Assign call to agent	`attendant`
`POST`	`/api/v1/calls/:id/start`	Start call	`attendant`
`POST`	`/api/v1/calls/:id/complete`	Complete call	`attendant`
`POST`	`/api/v1/calls/:call_id/upload`	Upload file to call	`attendant`
`GET`	`/api/v1/calls/:call_id/tags`	Call tags	`attendant`
`POST`	`/api/v1/calls/:call_id/tags`	Add tag	`attendant`
`DELETE`	`/api/v1/calls/:call_id/tags/:tag_id`	Remove tag	`attendant`
`GET`	`/api/v1/calls/:call_id/transcript`	Call transcript	`attendant`
`GET`	`/api/v1/calls/:call_id/summary`	AI call summary	`attendant`
`POST`	`/api/v1/calls/:id/manager-notes`	Add manager note	`supervisor`

List Calls

Returns a paginated list of the tenant's calls.

GET /api/v1/calls

Query Parameters

Parameter	Type	Default	Description
`page`	`integer`	`1`	Page number
`page_size`	`integer`	`20`	Items per page
`sort_by`	`string`	`inserted_at`	Sort field
`sort_order`	`string`	`desc`	Sort direction
`status`	`string`	-	Filter by status: `queued`, `active`, `completed`, `missed`, `cancelled`
`department_id`	`uuid`	-	Filter by department
`user_id`	`uuid`	-	Filter by agent
`date_from`	`string`	-	Start date (ISO 8601)
`date_to`	`string`	-	End date (ISO 8601)
`search`	`string`	-	Search by customer name/email

Request Example

bash

curl -X GET "https://voki.avanter.com.br/api/v1/calls?page=1&page_size=10&status=completed&date_from=2026-02-01" \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter"

Success Response (200)

json

{
  "data": [
    {
      "id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
      "status": "completed",
      "department_id": "e5f6a7b8-c9d0-1234-efgh-567890123456",
      "department_name": "Suporte Técnico",
      "user_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "user_name": "João Silva",
      "customer_name": "Carlos Ferreira",
      "customer_email": "carlos@email.com",
      "customer_phone": "+5511999998888",
      "duration": 345,
      "wait_time": 12,
      "rating": 5,
      "notes": "Cliente precisava de ajuda com configuração",
      "has_recording": true,
      "started_at": "2026-02-15T14:30:00Z",
      "completed_at": "2026-02-15T14:35:45Z",
      "inserted_at": "2026-02-15T14:29:48Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "page_size": 10,
    "total_pages": 15,
    "total_count": 142
  }
}

Call Details

GET /api/v1/calls/:id

Request Example

bash

curl -X GET https://voki.avanter.com.br/api/v1/calls/1a2b3c4d-5e6f-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter"

Success Response (200)

json

{
  "data": {
    "id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
    "status": "completed",
    "department_id": "e5f6a7b8-c9d0-1234-efgh-567890123456",
    "department_name": "Suporte Técnico",
    "user_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "user_name": "João Silva",
    "customer_name": "Carlos Ferreira",
    "customer_email": "carlos@email.com",
    "customer_phone": "+5511999998888",
    "duration": 345,
    "wait_time": 12,
    "rating": 5,
    "notes": "Cliente precisava de ajuda com configuração",
    "has_recording": true,
    "recording_url": "/api/v1/calls/1a2b3c4d-5e6f-7890-abcd-ef1234567890/recording",
    "tags": [
      {
        "id": "t1a2b3c4-d5e6-7890-abcd-ef1234567890",
        "name": "Suporte",
        "color": "#3b82f6"
      }
    ],
    "started_at": "2026-02-15T14:30:00Z",
    "completed_at": "2026-02-15T14:35:45Z",
    "inserted_at": "2026-02-15T14:29:48Z"
  }
}

Assign Call

Assigns a queued call to an agent.

POST /api/v1/calls/:id/assign

Request Body (optional)

Field	Type	Required	Description
`user_id`	`uuid`	No	Agent ID (default: authenticated user)

Request Example

bash

curl -X POST https://voki.avanter.com.br/api/v1/calls/1a2b3c4d-5e6f-7890-abcd-ef1234567890/assign \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter" \
  -H "Content-Type: application/json"

Success Response (200)

json

{
  "data": {
    "id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
    "status": "assigned",
    "user_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "user_name": "João Silva"
  }
}

Start Call

Marks the effective start of the video call.

POST /api/v1/calls/:id/start

Request Example

bash

curl -X POST https://voki.avanter.com.br/api/v1/calls/1a2b3c4d-5e6f-7890-abcd-ef1234567890/start \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter"

Success Response (200)

json

{
  "data": {
    "id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
    "status": "active",
    "started_at": "2026-02-18T14:30:00Z"
  }
}

Complete Call

Marks the call as completed.

POST /api/v1/calls/:id/complete

Request Body (optional)

Field	Type	Required	Description
`notes`	`string`	No	Agent notes about the call

Request Example

bash

curl -X POST https://voki.avanter.com.br/api/v1/calls/1a2b3c4d-5e6f-7890-abcd-ef1234567890/complete \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter" \
  -H "Content-Type: application/json" \
  -d '{
    "notes": "Problema resolvido. Cliente satisfeito."
  }'

Success Response (200)

json

{
  "data": {
    "id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
    "status": "completed",
    "completed_at": "2026-02-18T14:45:00Z"
  }
}

File Upload

Uploads a file associated with a call (e.g., shared documents).

POST /api/v1/calls/:call_id/upload

Request

Send as multipart/form-data.

Field	Type	Required	Description
`file`	`file`	Yes	File to upload

Request Example

bash

curl -X POST https://voki.avanter.com.br/api/v1/calls/1a2b3c4d-5e6f-7890-abcd-ef1234567890/upload \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter" \
  -F "file=@document.pdf"

Success Response (201)

json

{
  "data": {
    "id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "filename": "document.pdf",
    "content_type": "application/pdf",
    "size": 245678,
    "url": "/uploads/calls/1a2b3c4d/documento.pdf"
  }
}

Call Tags

GET /api/v1/calls/:call_id/tags

bash

curl -X GET https://voki.avanter.com.br/api/v1/calls/1a2b3c4d-5e6f-7890-abcd-ef1234567890/tags \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter"

Add Tag

POST /api/v1/calls/:call_id/tags

bash

curl -X POST https://voki.avanter.com.br/api/v1/calls/1a2b3c4d-5e6f-7890-abcd-ef1234567890/tags \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter" \
  -H "Content-Type: application/json" \
  -d '{
    "tag_id": "t1a2b3c4-d5e6-7890-abcd-ef1234567890"
  }'

Remove Tag

DELETE /api/v1/calls/:call_id/tags/:tag_id

bash

curl -X DELETE https://voki.avanter.com.br/api/v1/calls/1a2b3c4d-5e6f-7890-abcd-ef1234567890/tags/t1a2b3c4-d5e6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter"

Call Status

Status	Description
`queued`	In queue waiting for an agent
`assigned`	Assigned to an agent
`active`	Video call in progress
`completed`	Finished
`missed`	Not answered (timeout)
`cancelled`	Cancelled by the customer
`abandoned`	Abandoned (expired in queue)

Call Transcript

Returns the automatically generated transcript from the call (when the transcription feature is enabled in the plan).

GET /api/v1/calls/:call_id/transcript

Request Example

bash

curl -X GET https://voki.avanter.com.br/api/v1/calls/1a2b3c4d-5e6f-7890-abcd-ef1234567890/transcript \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter"

Success Response (200)

json

{
  "data": {
    "call_id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
    "transcript": "Agent: Good morning, how can I help you?\nCustomer: I need technical support...",
    "language": "pt-BR",
    "generated_at": "2026-02-18T14:46:00Z"
  }
}

Errors

Status	Description
`403`	Feature `transcription` not available in the plan
`404`	Call not found or no transcript available

AI Call Summary

Returns the AI-generated summary after call completion (available in plans with the ai_summaries feature).

GET /api/v1/calls/:call_id/summary

Request Example

bash

curl -X GET https://voki.avanter.com.br/api/v1/calls/1a2b3c4d-5e6f-7890-abcd-ef1234567890/summary \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter"

Success Response (200)

json

{
  "data": {
    "call_id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
    "summary": "The customer contacted us to resolve a configuration issue...",
    "provider": "openai",
    "model": "gpt-4o-mini",
    "generated_at": "2026-02-18T14:46:30Z"
  }
}

Errors

Status	Description
`403`	Feature `ai_summaries` not available in the plan
`404`	Call not found or no summary available

Manager Notes

Adds manager notes to a completed call. Notes are append-only (added with timestamp and author), not replaced.

Allowed roles: owner, manager, supervisor

POST /api/v1/calls/:id/manager-notes

Request Body

Field	Type	Required	Description
`notes`	`string`	Yes	Manager note text

Request Example

bash

curl -X POST https://voki.avanter.com.br/api/v1/calls/1a2b3c4d-5e6f-7890-abcd-ef1234567890/manager-notes \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter" \
  -H "Content-Type: application/json" \
  -d '{
    "notes": "Excellent service. Request customer feedback."
  }'

Success Response (200)

json

{
  "data": {
    "id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
    "manager_notes": "[2026-02-18 14:50 - Ana Supervisor] Excellent service. Request customer feedback."
  }
}

Errors

Status	Description
`403`	Only owner, manager, or supervisor can add notes
`404`	Call not found
`422`	Field `notes` is empty

Call Reconnection

When a participant disconnects during an active call, the system initiates a 60-second grace period for automatic reconnection. The end_reason field indicates how the call was terminated.

Reconnection Fields

Field	Type	Description
`disconnected_at`	`datetime`	Disconnection timestamp (null if none occurred)
`reconnected_at`	`datetime`	Reconnection timestamp (null if did not reconnect)
`end_reason`	`string`	Termination reason: `normal`, `timeout`, `disconnect`, `abandoned`

Reconnection Flow

Participant disconnects -> peer_disconnected event sent via WebSocket
60-second timer starts on the frontend (reconnecting UI with countdown)
If reconnected within 60s -> peer_reconnected event -> WebRTC renegotiation
If not reconnected -> call terminated with end_reason: "disconnect"

Calls ​

Endpoints ​

List Calls ​

Query Parameters ​

Request Example ​

Success Response (200) ​

Call Details ​

Request Example ​

Success Response (200) ​

Assign Call ​

Request Body (optional) ​

Request Example ​

Success Response (200) ​

Start Call ​

Request Example ​

Success Response (200) ​

Complete Call ​

Request Body (optional) ​

Request Example ​

Success Response (200) ​

File Upload ​

Request ​

Request Example ​

Success Response (201) ​

Call Tags ​

List Tags ​

Add Tag ​

Remove Tag ​

Call Status ​

Call Transcript ​

Request Example ​

Success Response (200) ​

Errors ​

AI Call Summary ​

Request Example ​

Success Response (200) ​

Errors ​

Manager Notes ​

Request Body ​

Request Example ​

Success Response (200) ​

Errors ​

Call Reconnection ​

Reconnection Fields ​

Reconnection Flow ​

Calls

Endpoints

List Calls

Query Parameters

Request Example

Success Response (200)

Call Details

Request Example

Success Response (200)

Assign Call

Request Body (optional)

Request Example

Success Response (200)

Start Call

Request Example

Success Response (200)

Complete Call

Request Body (optional)

Request Example

Success Response (200)

File Upload

Request

Request Example

Success Response (201)

Call Tags

List Tags

Add Tag

Remove Tag

Call Status

Call Transcript

Request Example

Success Response (200)

Errors

AI Call Summary

Request Example

Success Response (200)

Errors

Manager Notes

Request Body

Request Example

Success Response (200)

Errors

Call Reconnection

Reconnection Fields

Reconnection Flow