# Carbon Voice + Custom Integration ## Overview Carbon Voice is the [best interface](../concepts/why-carbonvoice.md) for talking to AI agents on the go. This document walks you through connecting any custom service to Carbon Voice — so your service can receive voice messages as transcripts via webhook and reply back using the Carbon Voice API. Connect Carbon Voice and your custom service so you can **talk** to your service like you would a chief of staff or other team member. ## Features of this Integration - **Talk to it with swipe of a button** — Record voice messages that are sent to your custom service via webhook while on-the-go with the mobile app - **Talk to it with a desktop shortcut** — Start talking to your agent with a single keyboard shortcut - **Send even when agent is offline and recovers** — Your messages are queued and delivered when your service comes back online - **Full API control** — Use the Carbon Voice API to send replies, mark messages as read, and attach files --- # What You'll Need * A Carbon Voice account * A service or server that can receive HTTP webhooks and make API calls * About 10 minutes 3 quick steps: 1. Create a Carbon Voice Agent Account 2. Register your Webhook and get your PAT 3. Use the API to send messages back --- # How it works under the hood ![Carbon Voice agent message flow](../../config/images/cv_agent_message_flow_v2.svg) The purple boxes are your agent. Carbon Voice handles the rest. --- # **Step 1** **Create a Carbon Voice Agent Account** Your integration runs as a dedicated "Agent" account in Carbon Voice — an identity separate from your account. 1. Go to [https://developer.carbonvoice.app](https://developer.carbonvoice.app) and log in 2. Click **"Agents"** in the left sidebar, then **"Create Agent"** 3. Name your agent (e.g. "My Service Bot") --- # **Step 2** **Register your Webhook and get your PAT** ### **Register your Webhook** Your webhook endpoint is the URL Carbon Voice will POST to whenever a new message is sent to your agent. 1. On the Agent Setup page, scroll down to **"Webhook subscription"** 2. Enter your webhook URL 3. Configure message filters as needed (e.g. ignore messages the agent sends itself) 4. Click **Subscribe** Carbon Voice will now POST a JSON payload to your endpoint each time a message arrives. The transcript of what was said is in the `transcript_txt` field of the payload. For full details on the webhook payload shape and event types, see: - [How to Register for Webhooks](https://api.carbonvoice.app/ai-docs/api-how-to/how-to-register-for-webhooks.md) - [Webhook Events Reference](https://api.carbonvoice.app/ai-docs/reference/webhook-events.md) ### **Get a Personal Access Token (PAT)** Your PAT authenticates API calls your service makes back to Carbon Voice. 1. On the Agent Setup page, scroll down to **"Personal access tokens"** 2. Click **"Create token"**, give it a name (e.g. "my-service"), and click **Create** **Save the token immediately** — it cannot be retrieved again. If lost, you'll need to create a new one. Use the token as a Bearer token in your API requests: ``` Authorization: Bearer ``` See [How to Authenticate](https://api.carbonvoice.app/ai-docs/api-how-to/how-to-authenticate.md) for more detail. --- # **Step 3** **Use the API to send messages back** Once your webhook is firing and you have a PAT, you can call the Carbon Voice API from your service. ### **Key fields from the incoming webhook** When Carbon Voice POSTs to your webhook, pull these fields from the payload to use in your reply: | Field | Use | | ----- | ----- | | `channel_id` | The conversation to reply into | | `message_guid` | The message ID (use as `reply_to_message_id` if it's a top-level message) | | `parent_message_id` | Set if the incoming message is already a reply — use this as `reply_to_message_id` instead | | `transcript_txt` | The text of what was said | ### **How-to guides** Use the following guides for the most common operations your integration will need: - [How to Send a Message](https://api.carbonvoice.app/ai-docs/api-how-to/how-to-send-a-message.md) — reply to an incoming message with text or audio - [How to Mark Messages as Read](https://api.carbonvoice.app/ai-docs/api-how-to/how-to-mark-messages-as-read.md) — clear the notification after processing - [How to Attach a Link](https://api.carbonvoice.app/ai-docs/api-how-to/how-to-attach-a-link.md) — add tappable link cards to a message - [How to Attach a File](https://api.carbonvoice.app/ai-docs/api-how-to/how-to-attach-a-file.md) — attach files to a message - [How to Identify Yourself (whoami)](https://api.carbonvoice.app/ai-docs/api-how-to/how-to-identify-yourself.md) — verify your agent's identity and user ID - [How to Message an Email Address](https://api.carbonvoice.app/ai-docs/api-how-to/how-to-message-new-people.md) — start a new conversation with someone by email For the full API reference: [OpenAPI spec](https://api.carbonvoice.app/docs/ai-agent-json) --- # Troubleshooting | Problem | Solution | | ----- | ----- | | Webhook not firing | Verify the URL is correct in the Agent Setup and that your server is publicly reachable | | Agent replies to itself | Add a filter in your webhook subscription to exclude messages where `creator_id` matches your agent's user ID (get it from `GET /whoami`) | | Replies go to wrong channel | Make sure you're using `channel_id` from the incoming webhook payload, not a hardcoded value | | 401 Unauthorized | Check your PAT is correct and being sent as `Bearer ` in the `Authorization` header | **Need help?** Reach out in Carbon Voice: Settings → Help → Support