# Carbon Voice + Tasklet

## Overview

Carbon Voice is the [best interface](../concepts/why-carbonvoice.md) for talking to AI agents on the go.

[Tasklet.ai](https://tasklet.ai) enables you to create agents that can perform tasks with intelligence on your behalf. When connected, Tasklet becomes like a Chief of Staff you can talk to while on the go with quick conversations.

Connect Carbon Voice and Tasklet so you can **talk** to your Tasklet agent 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 to trigger Tasklet tasks instantly 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 Tasklet comes back online
- **Full tool access** — Tasklet responds with full access to your calendar, email, web search, and more

---

# What You'll Need

* Create a Carbon Voice "AI Agent" account with API Access  
* A Tasklet.ai account  
* About 10 minutes

5 quick steps:
1.) Create Tasklet Agent and associated webhooks
2.) Get Credentials for Carbon Voice Agent Account
3.) Connect Tasklet to the Carbon Voice API
4.) Test it
5.) Connect other services to setup your agent's capabilities

# 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 Tasklet Agent and associated webhooks**

#### **Create Agent**

![tasklet_new_agent](../images/tasklet_new_agent.png)

1) Go to [tasklet.ai](http://tasklet.ai).  
2) Tap “New Agent in top left”

#### **Create a Trigger**
Enter this prompt and send it to the agent.
```
Set up a Webhook trigger named "CV Webhook"
```

![tasklet_setup_webhook](../images/tasklet_setup_webhook.png)

Copy the URL from the lightning bolt \-\> 3 dots \-\> Copy URL.  Save it somewhere, you’ll need it in later steps.  
![tasklet_setup_trigger](../images/tasklet_setup_trigger.png) 

---

# **Step 2** **Get Credentials for Agent Account**

### **Create Agent Account**

1) Go to [https://developer.carbonvoice.app](https://developer.carbonvoice.app) and Login to your account.
2) Click "Agents" on the left side and then click "Create Agent"
3) Name your agent (Something like "Hal (Travis AI EA)”)

### **Get Personal Access Token (PAT) for this Bot Account**


1) On the Agent Setup, scroll down to the "Personal access tokens" section and tap "Create token"
   1) Name it “Tasklet”
   2) Hit Create Token

You’ll be given the token.  *Make sure to save this, it can not be retrieved again.*  You’ll have to create a new one if you lose it.

(You will see a Webhook subscription section below. You can skipp this as the agent will register itself in steps below.)

--- 

# **Step 3** **Connect Tasklet to the Carbon Voice API**

Now we'll create a managed API connection in Tasklet so your agent can talk to the Carbon Voice API. This ensures credentials are properly stored and the connection is visible in your Manage Connections panel.

### **3a) Create the API connection**

Enter this prompt into your Tasklet agent. 
⚠️ **IMPORTANT:** Make sure to enter the Personal Access Token (PAT) you created in Step 2.

```
Create a Direct API connection to CarbonVoice with these settings:
- Service name: CarbonVoice
- Description: Voice-first async messaging platform. Send and receive voice messages, manage conversations, and handle webhooks.
- Base URL: https://api.carbonvoice.app
- Auth: Bearer token using this Personal Access Token: <⚠️ENTER PERSONAL ACCESS TOKEN FROM STEP 2⚠️>
- HTTP methods: GET, POST, PUT, DELETE
- Test it with: GET /whoami (should return the bot's user info)

Add these notes to the connection:
- OpenAPI spec: https://api.carbonvoice.app/docs/ai-agent-json
- How-to guides: https://api.carbonvoice.app/ai-docs/index.json
- Send messages with POST /v3/messages/start using is_text_message: true
- Attach links with POST /messages/{message_id}/attachments using {"attachments":[{"type":"link","link":"<url>"}]}
- Mark messages as read with DELETE /notifications/{channel_guid}/{message_guid}?type=message&notificationRemovalMode=hard
```
Tasklet will present a connection card for you to approve. Once approved, verify it worked:

> ✅ **Verify:** Open **Manage Connections** (gear icon in the left sidebar). 
> You should see "CarbonVoice" listed. If not, ask Tasklet to retry.

### **3b) Subscribe to Webhooks**

Now tell your agent to register for Carbon Voice message events so it wakes up when you send a voice message.

⚠️ **IMPORTANT:** Make sure to enter the `webhookURL` with the webhook URL you copied in Step 1.

```
Using the CarbonVoice API connection:

1. Call GET /whoami to identify the bot's user ID
2. Subscribe to webhooks by calling POST /apps/subscribe with:
   - webhookURL: <⚠️ENTER WEBHOOK URL FROM STEP 1⚠️>
   - subscriptions: ["message.posted.to.channel"]
   - filters: [{"field":"creator_id","operator":"neq","value":"<bot's user ID from /whoami>"}]
```

### **3c) Setup the Webhook Handler**

Finally, tell your agent how to handle incoming messages:

```
When you receive a webhook from Carbon Voice:
1. Read the transcript from the message payload (use the transcript_txt field)
2. Mark the message as read
3. Generate a helpful response — use my calendar, email, web search, or any other tools as needed
4. Reply in the same conversation thread
5. Format responses with paragraph breaks between thoughts — they'll be read aloud as speech
6. If your response includes any links, attach them to the message so they appear as tappable cards
```
Note: Personal Access Tokens are sensitive. Tasklet stores them securely within the managed connection, but be careful with screenshots of your chat history that might show the token.

# **Step 4** **Test it**

Test to make sure your Tasklet agent is setup to talk to Carbon Voice and you can reply back.

Enter this into Tasklet

```
- Now send me a Carbon Voice message as a DM via <enter your Carbon Voice email address>
```

If that comes through, then send a message back to see if it receives it and can respond.

You can watch in the Tasklet interface to verify that the webhook is firing in Tasklet and the reply it’s generating.

**Any issues**
Reach out to us in Carbon Voice and we can help you debug.  Settings -> Help -> Support

# **Step 5** **Connect other Services**

Once the basic setup works, connect additional services so your voice assistant can answer richer questions and act like a chief of staff or admin.  Connect:

* Calendar — "What's on my calendar today?"  
* Gmail — "Do I have any emails from John?" / "Send an email to Sarah"  
* Web search — "What's the latest news on X?"

---

# **Step 6** **Refine with these tips**

This gets your basic setup going.  Below are a few ways to improve your results.

* **Make the admin YOUR admin.**  Teach your admin your preferences.  Like any admin, you’ll want to train your agent with how to handle work on your behalf, when to reach out to you, when to execute and report.  
* **Security/ separating AI Agent knowledge:** A good chief of staff can reach out on your behalf as the agent, so it’s not confuse as being you reaching out.  If your agent is going to reach out to others, it’s encouraged to create two agents:  
  * Agent for you \- This has access to more of your tools and is told to only get messages from you in the webhook registration.  
  * Agent for interacting with others \- This one will not register to messages from you and will have limited tool access. It’s instructed to react to others in a guarded way. IE, an agent may tell you who you are meeting with, but an outside would be told to only share availability according to your rules.  
* **Sending or Reading Carbon Voice as You \-** If you want the agent to send Carbon Voice messages as if it is you, connect your agent to the Carbon Voice MCP (mcp.carbonvoice.app).  This then let’s it check on messages and send messages as if it was your user, not to be confused with the webhooks / API access from above where it is sending/ receiving as itself.

# **Troubleshooting**

| Problem | Solution |
| ----- | ----- |
| No reply received | Check that your webhook URL is correctly registered with Carbon Voice |
| Agent replies to itself | Make sure you've configured the Carbon Voice Agent Account to not receive it's own messages. |
| Replies go to wrong channel | Tell the agent to send messages to same channel\_guid from the incoming payload. For replies it should also use the reply_to_message_id passing the parent_id message of the thread.|

---