Carbon Voice + Custom Integration
About this integration
- Talk to your service — 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 webhook with a single keyboard shortcut
- Full API control — Use the Carbon Voice API to send replies, mark messages as read, and attach files
1 - Create an Agent Account (Optional: Get PAT if accessing the API)
- Create an agent
- If you want your webhook to send replies back to Carbon Voice, generate a Personal Access Token (PAT) for that agent
- Copy the PAT - you'll need it for API calls
2 - Connect your agent
Register your Webhook
Your webhook endpoint is the URL Carbon Voice will POST to whenever a new message is sent to your agent.
- On the Agent Setup page, scroll down to "Webhook subscription"
- Enter your webhook URL
- Configure message filters as needed (e.g. ignore messages the agent sends itself)
- Click Subscribe
Carbon Voice will now POST to your webhook URL whenever a new message is sent to your agent. The payload will contain the message text (transcript_txt) and other metadata.
For more details on how to process messages coming to the agents or make API calls, see the "How-to guides below.
3 - Talk to your agent
Get desktop app to setup hotkeys to talk to your agent. Get mobile app to talk to your agent on the go. Download Carbon Voice
How-to guides
Use the following guides for the most common operations your integration will need:
- How to Handle Incoming Webhook Payloads for details on the payload structure and common patterns.
- How to Send a Message — reply to an incoming message with text or audio
- How to Mark Messages as Read — clear the notification after processing
- How to Attach a Link — add tappable link cards to a message
- How to Attach a File — attach files to a message
- How to Identify Yourself (whoami) — verify your agent's identity and user ID
- How to Message an Email Address — start a new conversation with someone by email
For the full API reference: OpenAPI spec
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 conversation_id from the incoming webhook payload, not a hardcoded value |
| 401 Unauthorized | Check your PAT is correct and being sent as Bearer <token> in the Authorization header |
Need help? Reach out in Carbon Voice: Settings → Help → Support
Security Notes
- Your Carbon Voice PAT is stored in your service configuration — never commit it to version control
- Use webhook filters to restrict who can send messages to your agent