---
title: "External Voice Conversations"
slug: "external-voice-conversations"
updated: 2025-08-12T05:37:58Z
published: 2025-08-12T05:37:58Z
---

> ## 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,
    "ManagerId": 28361974,
    "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 Remarks

  

After the voice call ends, the Voice Platform will update the created Voice Conversation in CommBox with the links to the Recording and Transcript (Optional) using the following endpoint:  

**POST** [/objects/{object_Id}/remarks](/objects/%7Bobject_Id%7D/remarks)

Recording Link Example: POST [https://api.commbox.io/objects/63014142/remarks](https://api.commbox.io/objects/63014142/remarks)

```
{
    "data": {
        "Text": "http://10.98.1.71/OptimusIntegration/Rest/BroadsoftRecordingIntegration.aspx/GetRecordCall?callId=104684&internetType=2",
        "ManagerId": 28361974
    }
}
```

Additional Context Example: POST [https://api.commbox.io/objects/63014142/remarks](https://api.commbox.io/objects/63014142/remarks)

```
{
    "data": {
        "Text": "Customer called to ask about the Gas prices and wanted to pay 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)