---
title: "External Voice Conversations"
slug: "external-voice-conversations"
updated: 2026-08-27T12:44:37Z
published: 2026-08-27T12:44:37Z
canonical: "help.commbox.io/external-voice-conversations"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://help.commbox.io/llms.txt
> Use this file to discover all available pages before exploring further.

# External Voice Conversations

## Overview

CommBox’s voice integration enables seamless management of external voice conversations within the CommBox environment. This guide outlines how to create and manage a voice conversation in CommBox that originates from **an external voice platform**.

By leveraging a set of API calls, you can: • Create voice conversation objects in CommBox • Assign them to available agents • Attach recordings and transcripts • Properly resolve the conversation

**Note:** All API calls must include the appropriate channel ID.

**Conversation Lifecycle** This integration supports the full lifecycle of voice interaction:

- **Conversation Creation** – Create a new voice conversation with appropriate metadata.
- **Agent Assignment** – Assign the conversation to an agent in CommBox based on the availability, granted permissions, and assigned roles.
- **Call Documentation** – Add recordings, transcripts, and remarks.
- **Conversation Resolution** – Close the interaction correctly.

## Conversation Creation

 

To open a conversation in CommBox, use the following endpoint: **POST** [/streams/{streamId}/objects](/streams/%7BstreamId%7D/objects) The Stream ID is the CommBox-generated number/code for the channel.

**Key Fields:**

- "Type": 8 – Voice conversation type. See: /Enums/ObjectType
- "StatusId": 8 – Conversation in-process. See: /Enums/ObjectStatusType
- "conversation_status": "CONNECTED"
- "call_direction": "INCOMING"
- "agent_id": {agentId}
- "to": phone number including country code
- "call_duration": ""

**Payload Example:**

**POST** [https://api.commbox.io/streams/9MhWTiey6VKlmSoWFeLZuw%3d%3d/objects](https://api.commbox.io/streams/9MhWTiey6VKlmSoWFeLZuw%3d%3d/objects)

```
{
  "data": {
    "Type": 8,
    "StatusId": 8,
    "StreamProviderType": 5,
    "StreamProviderId": "9ydggtfgtM5hWTiehy6VjKfglmSoWFdyddsff5e",
    "UserStreamProviderId": "972587161499",
    "UserStreamProviderType": 5,
    "Content": {
      "conversation_status": "CONNECTED",
      "call_direction": "INCOMING",
      "agent_id": "28361974",
      "to": "972587161499",
      "call_duration": ""
    },
    "Message": "Aspire Voice Conversation 4"
  }
}
```

## Conversation Assignment

Once the conversation is created, assign it to a designated agent in CommBox* using the following endpoint: **POST** [/managers/{agent_Id}/assignments?objectId={conversation_Id}](/managers/%7Bagent_Id%7D/assignments?objectId=%7Bconversation_Id%7D)

**Key Fields:** • "agent_Id ": A CommBox-generated number for the agent. • “conversation_Id “: A CommBox-generated number for the conversation (object)

**Payload Example:**

**POST** https://api.commbox.io/managers/28361974/assignments?objectId=69716571

[*] To retrieve the agent ID, use this API: [Get Managers](https://help.commbox.io/apidocs/get-managers-1)

## Add Recording and Transcription

 

After the voice call ends, you can add the call recording and transcription to the Voice Conversation in CommBox.

### Upload and Transcribe a Recording

If you want to upload the call recording and have it transcribed in CommBox, we recommend using the **[Transcribe a Call Recording API](https://help.commbox.io/apidocs/transcribe-a-call-recording)**.

This API adds the recording to the conversation and processes it for transcription. The resulting transcript is added to the conversation as speaker-attributed messages.

The recording can be provided in one of the following ways:

- **File upload** – Upload the audio file directly using `multipart/form-data`.
- **Recording path** – Provide the path to a recording on the Voice channel's configured recording domain.
- **Existing recording activity** – Provide the `activity_id` of a call recording that already exists in the CommBox conversation.

Use the CommBox **Object ID** of the Voice Conversation when submitting the transcription request.

For the complete request structure, parameters, and examples, see [Transcribe a Call Recording](https://help.commbox.io/apidocs/transcribe-a-call-recording).

### Add Additional Remarks

To add additional textual information or context to the conversation, use the following endpoint:

**POST** `/objects/{object_Id}/remarks`

For example, you can use a remark to add a call summary or other information received from the external Voice platform.

**Example:**

```
{
  "data": {
    "Text": "Customer called to ask about the gas prices and wanted to pay for 3 gallons in advance.",
    "ManagerId": 28361974
  }
}
```

![Added remarks.png](https://cdn.document360.io/cce107c7-3390-46bd-a6cf-3120b27c4105/Images/Documentation/Added%20remarks.png)

## Set Conversation to Resolved

**Step I:** Set the Call status to DISCONNECTED using this endpoint: [/objects/{object_Id}/content](/objects/%7Bobject_Id%7D/content)

**Key Fields:** • "conversation_status": "DISCONNECTED" • "call_direction": "INCOMING" • "agent_id": {agentId} • "to": phone number including country code • "call_duration": ""

**Payload Example:**

**POST** [https://api.commbox.io/objects/69716571/content](https://api.commbox.io/objects/69716571/content)

```
{
    "data": {
        "conversation_status": "DISCONNECTED",
        "call_direction": "INCOMING",
        "agent_id": "28361974",
        "to": "441394420749",
        "call_duration": ""
    }
}
```

**Step II:** Set the Conversation to Resolve (and the Agent gets unassigned) using this endpoint:

POST [/objects/{object_Id}/status/2](/objects/%7Bobject_Id%7D/status/2)

Conversation Status: /Enums/ObjectStatusType (2 is Resolved)

Example: **POST** [https://api.commbox.io/objects/69716571/status/2](https://api.commbox.io/objects/69716571/status/2)

![Added remarks and Resolved.png](https://cdn.document360.io/cce107c7-3390-46bd-a6cf-3120b27c4105/Images/Documentation/Added%20remarks%20and%20Resolved.png)