Carbon Voice API (1.0.0)

Download OpenAPI specification:Download

URL: https://carbonvoice.app/support Terms of Service

Introduction

This API is designed for people who feel comfortable integrating with RESTful APIs.

Terminology

Workspace: An area that groups together people and Conversations.
Conversation: A channel of communication. A grouping of people and messages related to a given topic.
Collaborators: A group of people who are part of a Conversation.
Discussion: Any post into a conversation
CarbonLink: A link (on a website, QR code, or phone call) to start a conversation.

BaseURL

This API is served over HTTPS.

All URLs referenced in the documentation have the following base: https://api.carbonvoice.app.

Authentication

There are three ways to authenticate with this API:

with an OAuth2 Access Token in the Authorization request header field (which uses the Bearer authentication scheme to transmit the Access Token)
with your Client ID and Client Secret credentials
with a PXToken

Each endpoint supports only one option.

oauth2

Security Scheme Type: OAuth2

Flow type: implicit

Authorization URL: http://localhost:8081/oauth/authorize

Scopes:

admin -
Admin
identity -
View information about a user's identity
profile:read -
View a user's profile
profile:write -
Manage user's profile information: emails, phones, videocall, and more
channels:read -
View basic information about users's channels
channels:write -
Manage user's channels and create new ones on a user's behalf
channels:join -
Join user to an existing channel

Errors

Rate-Limiting

Errors

When an error occurs, you will receive an error object. Most of these error objects contain an error code and an error description so that your applications can more efficiently identify the problem.

If you get an 4xx HTTP response code, then you can assume that there is a bad request from your end. In this case, check the Standard Error Responses for more context.

5xx errors suggest a problem on our end, so in this case, check Carbon Voice's Status to see how our systems are doing.

In any other case you can use our support options.

Rate-Limiting

This API is subject to rate limiting. The limits differ per endpoint.

If you exceed the provided rate limit for a given endpoint, you will receive the 429 Too Many Requests response with the following message: Too many requests. Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.

For details on rate limiting, refer to Rate Limit Policy.

Support

If you have problems or need help with your case, you can always reach out to our Support.

Admin

Delete user

Authorizations:

oauth2

path Parameters

guid

required

string

Responses

Get users

Authorizations:

oauth2

Responses

Attachments (channels)

Add channel attachment

path Parameters

channelguid required	string
workspaceguid required	string

Request Body schema: application/json

Array

string

Responses

Request samples

Payload

Content type

application/json

["string"
]

Delete channel attachment

path Parameters

attachmentguid required	string
channelguid required	string
workspaceguid required	string

Responses

Update channel attachment

path Parameters

channelguid required	string
workspaceguid required	string

Request Body schema: application/json

object (UpdateAttachment)

Responses

Request samples

Payload

Content type

application/json

{ }

Attachments (messages)

Add message attachment Deprecated

path Parameters

messageguid

required

string

Request Body schema: application/json

object (AddAttachments)

Responses

Request samples

Payload

Content type

application/json

{ }

Add message attachment

path Parameters

messageguid

required

string

Request Body schema: application/json

object (AddAttachments)

Responses

Request samples

Payload

Content type

application/json

{ }

Delete message attachment Deprecated

path Parameters

attachmentguid required	string
messageguid required	string

Responses

Delete message attachment

path Parameters

attachmentguid required	string
messageguid required	string

Responses

Update message attachment Deprecated

path Parameters

attachmentguid required	string
messageguid required	string

Request Body schema: application/json

object (RequestAttachment)

Responses

Request samples

Payload

Content type

application/json

{ }

Update message attachment

path Parameters

attachmentguid required	string
messageguid required	string

Request Body schema: application/json

object (RequestAttachment)

Responses

Request samples

Payload

Content type

application/json

{ }

Auth

Get current user info

Responses

Response samples

200

Content type

application/json

{ }

Login with Firebase

Exchange Firebase token by pxtoken

Responses

Logout

Removes http-only auth cookie

Responses

MagiclinkController_codeCheck

Responses

MagiclinkController_confirmed

Responses

MagiclinkController_get

Responses

MagiclinkController_magiclink

Responses

MagiclinkController_redeem

Responses

MagiclinkController_redeemnow

Responses

Channels

Add channel attachment

path Parameters

channelguid required	string
workspaceguid required	string

Request Body schema: application/json

Array

string

Responses

Request samples

Payload

Content type

application/json

["string"
]

Add collaborator

Request Body schema: application/json

object (AddCollaborators)

Responses

Request samples

Payload

Content type

application/json

{ }

Create direct message

Request Body schema: application/json

object (CreateDirectMessage)

Responses

Request samples

Payload

Content type

application/json

{ }

Create named conversation

Request Body schema: application/json

object (CreateNamedConversation)

Responses

Request samples

Payload

Content type

application/json

{ }

Delete channel attachment

path Parameters

attachmentguid required	string
channelguid required	string
workspaceguid required	string

Responses

Find DM match

Responses

Get available channels

path Parameters

workspaceguid

required

string

Responses

Get Channel by ID

path Parameters

channelguid

required

string

Responses

Get channel messages

path Parameters

channelguid required	string
workspaceguid required	string

query Parameters

count required	number
newer_than required	number
older_than required	number

Responses

Get recent channels

Request Body schema: application/json

object (RecentChannelsFilter)

Responses

Request samples

Payload

Content type

application/json

{ }

Get workspace channels

path Parameters

workspaceguid

required

string

Responses

Update channel attachment

path Parameters

channelguid required	string
workspaceguid required	string

Request Body schema: application/json

object (UpdateAttachment)

Responses

Request samples

Payload

Content type

application/json

{ }

Favorites

Manage logged in user favorites

Add new favorite

Request Body schema: application/json

entity_id required	string
type required	string Value: "channel"

Responses

Request samples

Payload

Content type

application/json

{"type": "channel",
"entity_id": "5e9f8f8f8f8f8f8f8f8f8f8"
}

Delete favorite by entity

query Parameters

entity_id required	string Example: entity_id=5e9f8f8f8f8f8f8f8f8f8f8
type required	string Value: "channel"

Responses

Delete favorite by ID

path Parameters

id

required

string

Example: 5e8f8f8f8f8f8f8f8f

The ID of the favorite element to delete

Responses

Get user favorites

query Parameters

type	string Value: "channel" Favorite type

Responses

Update favorites order

Request Body schema: application/json

ids

required

Array of strings

List of favorite IDs in the desired order

Responses

Request samples

Payload

Content type

application/json

{"ids": ["5e9f8f8f8f8f8f8f8f8f8f8",
"5e9f8f8f8f8f8f8f8f8f8f9"
]
}

Health Checks

Show app version and status

Responses

Response samples

200

Content type

application/json

{"name": "cv-api",
"hostname": "cv-api-774dbc4955-696zc",
"version": "develop-21173ca"
}

Home

Get app startup data

Responses

Response samples

200

Content type

application/json

{"notifications": [{"_id": "string",
"user_id": "string",
"type": "message",
"workspace_id": "string",
"channel_id": "string",
"parent_message_id": "string",
"message_id": "string",
"message": "string",
"created_on": "2019-08-24T14:15:22Z",
"created_at": "2019-08-24T14:15:22Z",
"from_user_id": "string",
"pushInfo": {"title": "string",
"subtitle": "string",
"body": "string",
"data": { }
}
}
],
"workspaces": [{"workspace_guid": "string",
"vanity_name": "string",
"workspace_name": "string",
"workspace_description": "string",
"image_url": "string",
"owner_guid": "string",
"type_cd": "string",
"created_by": "string",
"created_ts": 0,
"last_updated_ts": 0,
"creator_first_name": "string",
"creator_last_name": "string",
"role_cd": "string",
"plan_type": "string",
"channels": ["string"
],
"availableChannelCount": 0,
"collaborators": ["string"
],
"settings": { },
"phones": ["string"
]
}
],
"channels": [{"workspace_guid": "string",
"channel_guid": "string",
"channel_name": "string",
"channel_description": "string",
"bg_rrggbb": "string",
"txt_rrggbb": "string",
"channel_settings": "string",
"image_url": "string",
"is_private": "string",
"post_rule": "string",
"dm_hash": "string",
"last_updated_ts": 0,
"created_ts": 0,
"owner_name": "string",
"sms_phone": "string",
"json_collaborators": [{ }
],
"joined_ts": 0,
"is_favorite": "N",
"last_heard_ts": 0,
"last_posted_ts": 0,
"workspace_name": "string",
"workspace_image_url": "string",
"type": "directMessage",
"images": ["string"
],
"moreCount": 0,
"unread_cnt": 0,
"avatars": { },
"createdNew": { },
"settings": { },
"attachments": [{"_id": "string",
"creator_id": "string",
"created_at": "2019-08-24T14:15:22Z",
"type": "string",
"link": "string",
"active_begin": "2019-08-24T14:15:22Z",
"active_end": "2019-08-24T14:15:22Z",
"filename": "string",
"mime_type": "string",
"length_in_bytes": 0,
"location": { }
}
]
}
],
"contacts": [{ }
]
}

Get home screen data

Responses

Response samples

200

Content type

application/json

{"success": true,
"workspaces": [{"workspace_guid": "string",
"vanity_name": "string",
"workspace_name": "string",
"workspace_description": "string",
"image_url": "string",
"owner_guid": "string",
"type_cd": "string",
"created_by": "string",
"created_ts": 0,
"last_updated_ts": 0,
"creator_first_name": "string",
"creator_last_name": "string",
"role_cd": "string",
"plan_type": "string",
"channels": ["string"
],
"availableChannelCount": 0,
"collaborators": ["string"
],
"settings": { },
"phones": ["string"
]
}
],
"usedAccessToken": true
}

Labels

Apply label to message

path Parameters

labelguid required	string
messageguid required	string
workspace_guid required	string

Responses

Create label

Request Body schema: application/json

behavior required	string Enum: "removeOnListenStart" "removeWhenHeard" "persistent"
name required	string
space_guid required	string
type required	string Enum: "personal" "workspace" "system" "reaction"

Responses

Request samples

Payload

Content type

application/json

{"name": "string",
"behavior": "removeOnListenStart",
"type": "personal",
"space_guid": "string"
}

Delete label

path Parameters

guid

required

string

Responses

Get all labels for user

Responses

Get label by ID

path Parameters

guid

required

string

Responses

Remove label from message

path Parameters

labelguid required	string
messageguid required	string
workspace_guid required	string

Responses

Update label

path Parameters

guid

required

string

Request Body schema: application/json

behavior required	string Enum: "removeOnListenStart" "removeWhenHeard" "persistent"
name required	string
space_guid required	string
type required	string Enum: "personal" "workspace" "system" "reaction"

Responses

Request samples

Payload

Content type

application/json

{"name": "string",
"behavior": "removeOnListenStart",
"type": "personal",
"space_guid": "string"
}

Log

Log client error

Request Body schema: application/json

line required	number
msg required	string
url required	string

Responses

Request samples

Payload

Content type

application/json

{"msg": "string",
"url": "string",
"line": 0
}

Messages

Complete message

Responses

Delete message

path Parameters

messageguid

required

string

Responses

Get channel messages

path Parameters

channelguid required	string
workspaceguid required	string

query Parameters

count required	number
newer_than required	number
older_than required	number

Responses

Get message by ID

path Parameters

messageguid

required

string

Responses

Get message by Workspace, Channel, ID

path Parameters

channelguid required	string
messageguid required	string
workspaceguid required	string

Responses

Get message for user

path Parameters

unique_id

required

string

Responses

Get message replies

Responses

Get recent messages

query Parameters

channelguid required	string
useLastUpdated required	boolean

Responses

Get recent messages around

path Parameters

channelguid required	string
messageguid required	string

Responses

Get unverified messages

Responses

Get welcome message

path Parameters

workspaceguid

required

string

Responses

Start channel message

Request Body schema: application/json

object (StartChannelMessage)

Responses

Request samples

Payload

Content type

application/json

{ }

Start welcome message

Request Body schema: application/json

object (StartWelcomeMessage)

Responses

Request samples

Payload

Content type

application/json

{ }

Update message name

Request Body schema: application/json

object (SetMessageName)

Responses

Request samples

Payload

Content type

application/json

{ }

Update message notes

Request Body schema: application/json

object (AddNotes)

Responses

Request samples

Payload

Content type

application/json

{ }

Update message summary

Request Body schema: application/json

message_guid required	string
text required	string
workspace_guid required	string

Responses

Request samples

Payload

Content type

application/json

{"message_guid": "string",
"workspace_guid": "string",
"text": "string"
}

Update message transcript

Request Body schema: application/json

object (MessageTranscript)

Responses

Request samples

Payload

Content type

application/json

{ }

Notifications

Create Notification

Request Body schema: application/json

_id required	string
channel_id required	string
created_at required	string <date-time>
created_on required	string <date-time>
from_user_id required	string
message required	string
message_id required	string
parent_message_id required	string
required	object (PushInfo)
type required	string Enum: "message" "tag"
user_id required	string
workspace_id required	string

Responses

Request samples

Payload

Content type

application/json

{"_id": "string",
"user_id": "string",
"type": "message",
"workspace_id": "string",
"channel_id": "string",
"parent_message_id": "string",
"message_id": "string",
"message": "string",
"created_on": "2019-08-24T14:15:22Z",
"created_at": "2019-08-24T14:15:22Z",
"from_user_id": "string",
"pushInfo": {"title": "string",
"subtitle": "string",
"body": "string",
"data": { }
}
}

Delete Notification

path Parameters

guid

required

string

Responses

Tag

Request Body schema: application/json

object (Tag)

Responses

Request samples

Payload

Content type

application/json

{ }

OAuth2

Authenticate User

Request Body schema: application/json

client_id required	string The API Key given by the application
client_secret required	string The API Token given by the application
code required	string The authorization code when grant_type is set to "authorization_code"
exp required	number The expiration time of the assertion, specified as seconds since 00:00:00 UTC, January 1, 1970. This value has a maximum of 1 hour after the issued time.
grant_type required	string The type of grant you are requesting, "client_credentials","refresh_token","authorization_code"
iat required	number The time the assertion was issued, specified as seconds since 00:00:00 UTC, January 1, 1970.
password required	string The password when grant_type is set to "password_grant"
refresh_token required	string The refresh token only when grant_type is set to "refresh_token"
scopes required	Array of strings The list of the permissions (tpApps) that the application requests.
username required	string The username only when grant_type is set to "refresh_token"

Responses

Request samples

Payload

Content type

application/json

{"grant_type": "string",
"client_id": "string",
"client_secret": "string",
"exp": 0,
"iat": 0,
"scopes": ["string"
],
"refresh_token": "string",
"username": "string",
"password": "string",
"code": "string"
}

Response samples

200

Content type

application/json

{"access_token": "string",
"token_type": "string",
"refresh_token": "string",
"expires_in": 0,
"refresh_token_exp": 0,
"scope": "string"
}

Authorize User

query Parameters

client_id required	string Application client_id
redirect_uri required	string The URL to which Auth will redirect the browser after authorization has been granted by the user.
response_type required	string Use `code` for server side flows, and `token` for application side flows
scope required	string A space-delimited list of permissions that the application requires.
state required	string An opaque value the applications adds to the initial request that the authorization server includes when redirecting the back to the application. This value must be used by the application to prevent CSRF attacks.

Responses

Get Client by client_id

Responses

Response samples

200

Content type

application/json

{ }

Get User info

Responses

Response samples

200

Content type

application/json

{ }

Playlists

Create playlist

Request Body schema: application/json

name required	string
required	object (SearchParameters)

Responses

Request samples

Payload

Content type

application/json

{"search_parameters": {"label_guids": ["string"
],
"user_guids": ["string"
],
"begin_date": "2019-08-24T14:15:22Z",
"end_date": "2019-08-24T14:15:22Z",
"heardStatus": "heard",
"limit": 0
},
"name": "string"
}

Response samples

201

Content type

application/json

{"_id": "string",
"name": "string",
"search_parameters": {"label_guids": ["string"
],
"user_guids": ["string"
],
"begin_date": "2019-08-24T14:15:22Z",
"end_date": "2019-08-24T14:15:22Z",
"heardStatus": "heard",
"limit": 0
},
"image_url": "string"
}

Delete playlist

path Parameters

playlistguid

required

string

Responses

Get user playlists

Responses

Response samples

200

Content type

application/json

[{"_id": "string",
"name": "string",
"search_parameters": {"label_guids": ["string"
],
"user_guids": ["string"
],
"begin_date": "2019-08-24T14:15:22Z",
"end_date": "2019-08-24T14:15:22Z",
"heardStatus": "heard",
"limit": 0
},
"image_url": "string"
}
]

Update playlist

path Parameters

playlistguid

required

string

Request Body schema: application/json

name required	string
required	object (SearchParameters)

Responses

Request samples

Payload

Content type

application/json

{"search_parameters": {"label_guids": ["string"
],
"user_guids": ["string"
],
"begin_date": "2019-08-24T14:15:22Z",
"end_date": "2019-08-24T14:15:22Z",
"heardStatus": "heard",
"limit": 0
},
"name": "string"
}

Update playlist icon

path Parameters

playlistguid

required

string

Responses

Prerecorded Messages

Create prerecorded message

Request Body schema: application/json

object (CreatePrerecordedMessage)

Responses

Request samples

Payload

Content type

application/json

{ }

Delete prerecorded message

path Parameters

messageguid

required

string

Responses

Get prerecorded message

Responses

Reply with prerecorded message

path Parameters

channel_guid required	string
message_guid required	string
parent_message_guid required	string

Responses

Send prerecorded message

path Parameters

channel_guid required	string
message_guid required	string

Responses

Start prerecorded message

Request Body schema: application/json

object (StartPrerecordedMessage)

Responses

Request samples

Payload

Content type

application/json

{ }

Push

Save push token

Responses

Reactions

Add reaction to message

path Parameters

message_id required	string
reaction_id required	string

Responses

Get available reactions

Responses

Response samples

200

Content type

application/json

[{"id": "string",
"name": "string",
"image_url": "string",
"code": "string",
"reaction_tts": "string"
}
]

Remove reaction from message

path Parameters

message_id required	string
reaction_id required	string

Responses

Search

Search messages

Request Body schema: application/json

begin_date required	string <date-time>
end_date required	string <date-time>
heardStatus required	string Enum: "heard" "unheard" "any"
label_guids required	Array of strings
limit required	number
user_guids required	Array of strings

Responses

Request samples

Payload

Content type

application/json

{"label_guids": ["string"
],
"user_guids": ["string"
],
"begin_date": "2019-08-24T14:15:22Z",
"end_date": "2019-08-24T14:15:22Z",
"heardStatus": "heard",
"limit": 0
}

Response samples

200

Content type

application/json

{"messages": [{"message_guid": "string",
"creator_guid": "string",
"duration_ms": 0,
"word_cloud": "string",
"message_ts": 0,
"last_updated_at": 0,
"keywords_txt": "string",
"message_url": "string",
"transcript_txt": "string",
"workspace_guid": "string",
"channel_guids": ["string"
],
"waveform_url": "string",
"waveform_percentages": ["string"
],
"creator_image_url": "string",
"creator_first_name": "string",
"creator_last_name": "string",
"reply_count": 0,
"reply_summary": { },
"parent_message_guid": "string",
"heard_ms": 0,
"heard_pct": 0,
"data": { },
"unheard_replies": 0,
"audio_route": "string",
"attachments": ["string"
],
"heard_status": ["string"
],
"notes": "string",
"settings": { },
"notify": true,
"reaction_summary": { },
"name": "string",
"transcription_timecodes": ["string"
],
"is_text_message": true,
"unique_client_id": "string",
"status": "string"
}
],
"success": true,
"unheard_counts_by_channel": { }
}

Streaming

Get stream files signed URL

path Parameters

file required	string Example: stream.m3u8 Filename
message_id required	string Example: fd546db4b648d6b1fa Message ID

Responses

User

Delete user

Authorizations:

oauth2

path Parameters

guid

Payload

Content type

application/json

{ }

UserController_checkUser

query Parameters

method required	string
value required	string

Responses

UserController_createUnverifiedUser

Request Body schema: application/json

object (CreateUnverifiedUser)

Responses

Request samples

Payload

required

string

Responses

UserController_findUnverifiedUser

Responses

UserController_myIdentities

Responses

UserController_newIdentity

Request Body schema: application/json

object (NewIdentity)

Responses

Request samples

Payload

Content type

application/json

{ }

UserController_sessionsMerge

Request Body schema: application/json

object (SessionMerge)

Responses

Request samples

Payload

Content type

application/json

{ }

UserController_updateProfileEntry

Request Body schema: application/json

object (UpdateProfile)

Responses

Request samples

Payload

Content type

application/json

{ }

UserController_updateUserPreference

Request Body schema: application/json

object (UpdateUserPreference)

Responses

Request samples

Payload

Content type

application/json

{ }

UserController_userHeadshot

path Parameters

id

required

string

Responses

UserController_userMerge

Request Body schema: application/json

object (UserMerge)

Responses

Request samples

Payload

Content type

application/json

{ }

UserController_userProfile

path Parameters

id

required

string

Responses

Voicemail

Get voicemail phone numbers

Get a list of available phone numbers

query Parameters

areacode

required

string

Responses

Receive SMS webhook

This endpoint is called by AWS

Request Body schema: application/json

object (ReceiveSMS)

Responses

Request samples

Payload

Invite user to workspace

Request Body schema: application/json

email required	string
phone required	string
user_guid required	string
workspace_guid required	string

Responses

Request samples

Payload

Content type

application/json

{"workspace_guid": "string",
"user_guid": "string",
"email": "string",
"phone": "string"
}

Order workspace

Responses

Remove phone number from workspace

path Parameters

guid required	string
number required	string

Responses

Remove user from workspace

Request Body schema: application/json

user_guid required	string
workspace_guid required	string

Responses

Request samples

Payload

Content type

application/json

{"workspace_guid": "string",
"user_guid": "string"
}

Request to join a Workspace

path Parameters

id

required

string

Responses

Upsert workspace

Request Body schema: application/json

type_cd required	string
user_guid required	string
vanity_name required	string
workspace_description required	string
workspace_guid required	string
workspace_name required	string

Responses

Request samples

Payload

Content type

application/json

{"user_guid": "string",
"workspace_guid": "string",
"workspace_name": "string",
"workspace_description": "string",
"type_cd": "string",
"vanity_name": "string"
}