# Carbon Voice + Custom Integration

> **About this integration**
>
>[Why Carbon Voice?](../concepts/why-carbonvoice.md)
>
>- **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)

1. [Create an agent](../api-how-to/how-to-create-a-voice-agent-account.md)
2. If you want your webhook to send replies back to Carbon Voice, generate a Personal Access Token (PAT) for that agent
3. 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.

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 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](https://carbonvoice.app/download)


### How-to guides

Use the following guides for the most common operations your integration will need:

- [How to Handle Incoming Webhook Payloads](../api-how-to/how-to-handle-incoming-webhook-payloads.md) for details on the payload structure and common patterns.
- [How to Send a Message](../api-how-to/how-to-send-a-message.md) — reply to an incoming message with text or audio
- [How to Mark Messages as Read](../api-how-to/how-to-mark-messages-as-read.md) — clear the notification after processing
- [How to Attach a Link](../api-how-to/how-to-attach-a-link.md) — add tappable link cards to a message
- [How to Attach a File](../api-how-to/how-to-attach-a-file.md) — attach files to a message
- [How to Identify Yourself (whoami)](../api-how-to/how-to-identify-yourself.md) — verify your agent's identity and user ID
- [How to Message an Email Address](../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 `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