Guides

Everything you need to set up your AI agents and connect them to your favorite platforms. Written for non-technical users — no coding required.

Getting Started

You can hire your first AI specialist in under two minutes. No integrations needed up front — meet them, sign them on, then connect tools as you go.

1. Create an account at tamalebot.com. Enter your email and you'll get a sign-in code — no password needed.
2. Browse the team. Open /team to see every specialist on the bench — Zoe (social media), Maya (customer support), Danny (sales ops), Aviv (technical advisor), Priya (executive assistant), Aria (data analyst), Iris (legal), and more. Each card shows what they do, what they won't do, and which tools they need.
3. Click Hire on the one you want. The hire page shows their portrait, resume, will-do / won't-do bullets, integrations they'll plug into, the monthly cost broken down line by line, and any liability acknowledgments specific to their role.
4. Pick a tier. Most specialists offer Associate (default, Sonnet-class model + $50/mo of LLM tokens included) and Senior (Opus-class model + $100/mo of LLM tokens included). A few specialists are Senior-only because their job demands the strongest reasoning. The math under the chooser shows exactly what you'll pay.
5. Give them an internal handle (e.g. danny or zoe-acme). This is just for the dashboard URL.
6. Sign the acknowledgments and click Hire. Your agent boots in about 30 seconds and sends a short in-character acceptance message ("Hey boss, Danny here. Thanks for the seat…").
7. Go to My Agents and open them. Start chatting to see how they work, then connect integrations from the Integrations tab when you're ready.

Use Case Guides

Each guide below shows you what the agent does, which platforms to connect, and exactly what to tell it.

📷 Social Media Manager

What it does: Creates content, publishes across platforms, tracks analytics over time, monitors competitors, manages engagement (comments and replies), and runs a content approval workflow — all on autopilot.

Which platforms to connect

• Instagram — feed posts, Reels, carousels, and Stories
• Facebook — text, photo, and video posts to your Page
• Threads — text, image, and video posts + monitoring
• Twitter/X — tweets with up to 4 images or video. Use the Integrations tab wizard for one-click setup with Simple Connect, or bring your own API keys.
• YouTube — Shorts upload (requires OAuth2 credentials — see setup below)
• TikTok — video posts (created as drafts — you approve them in the TikTok app before they go live)
• OpenAI — for generating images with DALL-E and editing/resizing media
• Slack — for receiving draft notifications and approving posts

Platform notes

• TikTok posts are drafts. Due to TikTok API restrictions, posts are created in draft status. You'll need to open the TikTok app and approve each draft before it goes live. This is a platform limitation, not a TamaleBot limitation.
• YouTube Shorts requires OAuth2. In addition to your YouTube API key, you need a refresh token and Google OAuth client credentials (GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET). The agent uses these to upload videos directly via the YouTube Data API.
• Instagram Stories expire in 24 hours. The agent can post Stories, but they auto-delete after 24 hours per Instagram's rules. Analytics for expired Stories may not be available.

Content approval workflow

By default, the agent does not auto-publish. Instead it follows a draft-review-publish flow:

1. Draft — The agent creates content and saves it as a pending draft.
2. Notify — It sends you a preview via Slack, Telegram, or email with the caption, hashtags, and media.
3. Review — Reply with "approve", "edit [your changes]", or "reject" for each draft.
4. Publish — Approved drafts are published immediately. Edits are updated and re-sent for approval.

Drafts older than 48 hours are flagged as stale. Once you trust the agent's quality, you can tell it to auto-publish.

Engagement preference

Publishing alone rarely produces followers on a new account. The agent can also follow, like, reply to, and quote-post other accounts to bootstrap reach — you control how aggressively from the Creative & Social Media card in your agent dashboard. Engagement is off by default (publish-only) so the agent never acts on other accounts until you opt in — turn it on when you're ready to grow.

Platform coverage: full engagement is Twitter/X only. Threads, Facebook, Instagram, and YouTube support comment replies but do not expose follow/like writes through their APIs. TikTok is publish-only — all engagement must be done manually in the TikTok app, regardless of mode.

What the agent can do

Suggested scheduled tasks

Set these up in your agent's Scheduled Tasks section. The agent will run each task automatically at the time you choose.

Example prompts you can use in chat

Tips

• Use the Integrations tab. The quickest way to connect X is the guided wizard in your agent's Integrations tab. It walks you through connecting your account, writing a content strategy, and picking a posting schedule — all in under a minute.
• Start with drafts. Let the agent create posts and send you previews before publishing. Once you trust the quality, switch to auto-publish.
• Use the weekly analytics task to catch trends early. The agent tracks metrics over time, so week-over-week comparisons get more useful the longer it runs.
• Set up the engagement check. Responding to comments quickly boosts your algorithm ranking. The agent handles routine replies and flags anything that needs your attention.
• Add your brand voice to the system prompt. The more context about your business, audience, and tone, the better the posts will be. The X wizard does this for you automatically when you fill in your content strategy.
• Rate limits: The agent automatically retries when a platform rate-limits it, but aggressive schedules (posting every few minutes) can still hit limits. Space tasks at least 30 minutes apart.

💬 Customer Support

What it does: An AI-powered customer support agent that answers questions from your docs, handles common requests, and escalates tricky issues to your team. Deploy it as an embeddable chat widget on your website, connect it to Slack or Discord for internal support, or both.

Deployment modes

• Website Widget — embed a chat bubble on your website so visitors can get instant answers 24/7
• Internal Agent — connects to Slack, Discord, WhatsApp, Telegram, or Email for team and customer channels
• Both — widget on your site + chat integrations for full coverage

How to deploy an AI customer chat widget

Get a working AI support chat on your website in under 5 minutes:

1. Upload your docs. Go to your TamaleBot dashboard → Knowledge Base. Upload your FAQs, product docs, pricing pages, return policies — anything your customers ask about. Supported formats: PDF, Word, text, markdown, images.
2. Go to /team and click Hire on Maya (Customer Support Agent).
3. Pick a tier on the hire page (Associate is fine for most sites; switch to Senior if you handle complex troubleshooting). Sign the acknowledgments.
4. Give Maya a handle (e.g. acme-support) and click Hire.
5. Open the agent from My Agents and go to Settings → Chat Widget. Customize greeting, brand color, daily cap, and copy the embed code:

7. Paste it into your website just before </body>. Works with any site — Shopify, WordPress, Squarespace, Webflow, static HTML, React, Next.js, etc.
8. Done. A chat bubble appears in the bottom-right corner. Your customers can ask questions and get instant answers from your documentation.

Which integrations to connect

• Slack or Discord — for escalation notifications when the agent can't answer a question
• Notion — connect your wiki or internal docs as an additional knowledge source
• Shopify (optional) — lets the agent look up orders, products, and customer accounts
• Stripe (optional) — lets the agent check payment status, subscriptions, and charges
• Email (optional) — for receiving support requests via email

What the agent can do

Scheduled tasks

• Unresolved Issue Review (9 AM weekdays) — reviews questions the agent couldn't answer in the past 24 hours, summarizes gaps, and suggests documentation updates
• Weekly Support Summary (Monday 9 AM, optional) — total conversations handled, most common topics, resolution rate, escalation count

Widget features

• Session persistence — visitors can refresh the page or come back later and continue their conversation
• Mobile responsive — full-width on phones, compact panel on desktop
• Shadow DOM isolation — the widget's styles never conflict with your site's CSS
• Customizable — brand color, greeting message, and position (left or right)
• "Powered by TamaleBot" badge — included on all plans
• Rate limiting — built-in protection against abuse (20 messages/hour per visitor, configurable daily cap)

Example prompts

Estimated costs

Maya bills as a single subscription per agent. Associate is $229/mo (Sonnet-class model + $50/mo of LLM tokens included); Senior is $339/mo (Opus-class model + $100/mo of LLM tokens included). Sub-agents and Always-On are bundled in, no add-on fees. The only variable is LLM overage if you blow past the included tokens. Here's what to expect at different volumes:

LLM token usage depends on conversation length. Short FAQ answers cost less; multi-turn troubleshooting costs more. Estimates assume ~3 messages per conversation on average. Overage is metered at managed-LLM rates and shows up on your invoice the following month.

Compare: Intercom starts at $39/mo (1 seat) with per-resolution charges that add up fast. Zendesk starts at $55/agent/mo plus per-AI-resolution fees. Maya is one flat seat that handles the whole site 24/7 with no per-resolution math.

Tips

• Upload everything your customers ask about. The agent can only answer from what it has access to. PDFs, markdown files, text docs, and images all work.
• Set clear escalation rules in your system prompt. Tell the agent exactly when to hand off: billing issues, account access, security concerns, anything outside the docs.
• Use the daily unresolved review. It surfaces gaps in your documentation. If the agent keeps getting questions it can't answer, that's a signal to add more docs.
• Connect Shopify or Stripe if your customers ask about orders or payments. The agent can look up specific orders and give real answers instead of generic instructions.
• Start with a low daily cap (e.g. 100) and increase it as you verify the agent handles questions well. This prevents unexpected costs during testing.
• Test before going live. Send the widget a few questions yourself to verify it finds the right answers from your docs. Check that escalation messages land in your Slack/Discord channel.

💰 Sales Ops Agent

What it does: A sales ops sidekick for your existing reps. Danny handles the 60% of the job reps hate — CRM hygiene, follow-up drafting, pre-meeting briefings, Monday pipeline digests, inbound lead routing — so your reps spend the day on calls, not in HubSpot. Approval-in-the-loop by default: drafts everything, sends nothing in a rep's voice without sign-off. Danny does not close deals. Your reps close. Danny makes them look prepared.

Getting started

1. Go to Browse specialists and click Hire on Sales Ops Agent.
2. Pick your CRM path. Danny will ask in his first conversation: plug into your existing CRM (HubSpot, Salesforce, or Pipedrive via one-click OAuth), or run his built-in pipeline tracker if you don't have a CRM. Either path supports the same workflow — deals, contacts, activities, stage progression. The internal tracker exports cleanly to a real CRM later if you outgrow it.
3. Connect Slack and Google Workspace in Settings → Integrations. Slack is Danny's main interface (briefings + draft approvals); Google Calendar is what powers pre-meeting briefings. Email (IMAP+SMTP) is a strong third.
4. Upload three required KB docs: pricing.pdf (or rate card), icp.md (who's a fit), and cadence.md (day 2 / 5 / 12 follow-up timing). Without these, Danny will ask you every time.
5. Upload nice-to-haves: email templates (so drafts sound like you), battle cards, 2–3 case studies, a routing doc (who owns which territory).
6. Tell Danny who your reps are — names, Slack handles, territories. A single message like "Bob handles US East, Alice handles US West, round-robin on SMB inbound" is enough.
7. The three scheduled tasks (morning briefings, follow-up drafts, Monday digest) are pre-configured on deploy. Review them before day one.

Which integrations to connect

• CRM (one of: HubSpot, Salesforce, Pipedrive, or Danny's built-in pipeline tracker) — everything Danny does touches a pipeline. The three connected CRMs use one-click OAuth from the Integrations tab. The built-in tracker needs zero setup and is viewable on your dashboard's Pipeline tab; it exports cleanly to a real CRM later when you outgrow it.
• Slack (required) — Danny DMs each rep with briefings and follow-up drafts, and DMs the sales manager with Monday digests. This is the main interface.
• Google Workspace (required for pre-meeting briefings) — Danny reads each rep's calendar to produce the 30-min-before-meeting briefing. This is the feature reps tell their friends about.
• Email / IMAP+SMTP (strongly recommended) — so Danny can read inbound prospect threads and log them to the right deal. Without it, CRM hygiene drops from "automatic" to "when the rep forwards a message".
• Stripe (optional) — for weekly revenue reconciliation against closed-won deals. Skip it unless you collect via Stripe.
• Notion (optional) — if your playbooks and meeting notes live there, Danny can reference them in briefings.

What Danny does (and doesn't)

Not in scope: closing deals (your reps close), cold outreach / mass sequences (no deliverability infrastructure), phone calls or SMS, LinkedIn DMs, disparaging competitors, or sending anything in a rep's voice without approval.

Scheduled tasks

These three are pre-configured when you deploy — the heart of Danny's job.

Example prompts

Estimated costs

Danny is one subscription per agent. Associate is $229/mo (Sonnet + $50/mo of LLM tokens included); Senior is $339/mo (Opus + $100/mo of LLM tokens included). Sub-agents and Always-On are bundled in. Most sales teams stay within the included token allowance unless their lead volume is high.

Token usage depends on task complexity. Simple lead qualification and Slack DMs cost less; multi-step prospect research with web browsing and large-context CRM lookups cost more. Overage is metered at managed-LLM rates.

Compare: HubSpot Sales Hub starts at $20/seat/mo (Starter) and goes up to $150/seat/mo (Professional) for sequences, automation, and forecasting — per rep. Danny is additive to your existing CRM seat cost: one $229 seat handles the admin work that would otherwise eat 3–4 hours a day across your whole team.

Tips

• Keep approval-in-the-loop on for the first two weeks. Reps edit Danny's drafts heavily at first; those edits are how his "voice model" learns your team's style. After ~50 drafts the edits get smaller. Only then consider flipping on auto-send for a narrow cadence.
• Upload your cadence doc first. Without it Danny doesn't know when day 2, day 5, day 12 are — and follow-up drafting is the single highest-ROI thing he does.
• Connect Google Workspace even if you think you won't use it. Pre-meeting briefings are the feature reps remember. A 30-second DM with deal stage, last 3 touches, and the right battlecard changes how a call starts.
• Configure your HubSpot deal stages first. Danny moves deals through your existing stages — if the stages don't match your real process, he'll make the mismatch worse.
• Start the stalled-deal alerts going to reps, not the manager. Reps like a heads-up; managers hate being copied on every "Bob hasn't touched ACME in 8 days" notification. Surface to the manager only in the Monday digest.
• Use Slack to talk to Danny from your phone. "Brief me on tomorrow's calls" and "Draft the next touch for ACME" work the same from a phone as from the dashboard.
• Danny does not close deals. If you need cold outreach at scale, phone calls, or mass sequences, pair him with a dedicated outbound tool — Danny's job is the warm pipeline, not the cold list.

📅 Executive Assistant ~15 minutes

What it does: Your AI chief of staff. Reads and triages your inbox, watches your calendar, drafts replies and scheduling requests, keeps your task list in Notion up to date, and delivers a morning briefing so your day starts with context instead of chaos. Works across Gmail, Google Calendar, Google Docs, Google Sheets, Google Drive, and Notion.

What the agent can actually do

• Email triage — reads your inbox, flags urgent threads, drafts replies (never sends without your approval unless you tell it to).
• Calendar management — checks your day/week, blocks focus time, finds open slots for meetings, suggests reschedules when things collide.
• Morning briefing — a scheduled summary of today's meetings, urgent emails, pending tasks, and the weather (yes, really).
• Task tracking — reads + writes Notion pages, appends to task databases, surfaces overdue items.
• Document lookup — reads Google Docs and Drive files to answer questions about your own stuff ("what did I agree in last week's contract?").
• Spreadsheet updates — appends rows to Google Sheets for tracking (expense logs, CRM, whatever you already manage in Sheets).
• Knowledge base — upload your SOPs, bios, meeting prep templates, company docs; the agent references them when relevant.

Setup — 15 minutes

1. Hire Priya (Executive Assistant). Open /team and click Hire on the Executive Assistant specialist.
2. Connect Google Workspace (Gmail + Calendar + Drive + Docs + Sheets) — one OAuth flow covers all five. Google Workspace setup →
3. Connect Notion (optional but recommended) for task tracking. Notion setup →
4. Connect Slack or Telegram so you can chat with the assistant from your phone ("what's on my calendar?" "draft a reply to the thread with Sarah").
5. Upload context to the Knowledge Base — your standard email signatures, company bios, meeting-prep templates, people you want auto-researched before a first meeting, etc.
6. Set up the morning briefing (see Suggested scheduled tasks below) so it runs automatically before your first meeting.

Which integrations to connect

• Google Workspace (recommended) — Gmail, Calendar, Drive, Docs, Sheets all unlock from one OAuth flow.
• Notion (recommended) — for task tracking, meeting notes, any knowledge your team already manages in Notion.
• Email (IMAP/SMTP) (alternative to Gmail) — if your inbox isn't on Google, the agent can connect via standard IMAP/SMTP.
• Slack or Telegram (recommended) — chat with the assistant from your phone.
• Knowledge Base — your personal context layer. The more you upload, the more useful the agent becomes.

Suggested scheduled tasks

Example prompts you can type in chat

Tips

• Don't give it send-email authority day one. Start with "show me drafts before sending." After a week of watching its drafts, turn on autosend for low-stakes categories.
• Upload your bios, templates, and SOPs to the Knowledge Base. Without that context, the agent writes generic replies. With it, the replies sound like you.
• Use scheduled tasks for the repetitive stuff. Morning briefing, end-of-day summary, meeting prep — these are where the agent pays back daily.
• Keep a "do not email" list in the system prompt or knowledge base — vendors, ex-clients, anyone you don't want the agent reaching out to.

📊 Data Analyst

What it does: Pulls data from your business tools, generates reports, tracks key metrics (KPIs), and posts summaries where your team can see them.

Which integrations to connect

• Stripe — revenue, subscriptions, charges, churn.
• Shopify — orders, products, customers.
• HubSpot — pipeline, deals, contacts.
• Google Sheets (via Google Workspace) — to write metrics into a dashboard you already maintain.
• Notion — for saving weekly / monthly reports.
• Slack or Telegram — chat with the agent to ask ad-hoc metrics questions from your phone. For pushing scheduled reports to a Slack channel, use the Webhook add-on on the agent.

Suggested scheduled tasks

Example prompts

How to get reports delivered to Slack

The agent itself doesn't push messages to Slack channels. For scheduled-report delivery, use the Webhook add-on:

1. Create an incoming webhook in your Slack workspace pointed at the channel you want (e.g. #metrics).
2. In the agent's Settings → Webhook field, paste the webhook URL and check the schedule.executed event.
3. When scheduled tasks complete, their output gets posted to that Slack channel automatically.

For ad-hoc questions ("what was revenue last week?"), the agent answers directly in whatever channel you message it through — Slack DM, Telegram, or dashboard chat.

Tips

• Start with one source. Connect Stripe first, set up the daily metrics task, see if the summaries are actually useful. Add Shopify / HubSpot / Sheets as you need them.
• Use Google Sheets as the system of record for trend-tracking. The agent can append rows daily and you end up with a real spreadsheet you can chart and share.
• Upload a KPI glossary to the Knowledge Base. Different teams calculate MRR / churn / LTV differently. The agent matches your definitions if you upload them.

𝕏 Twitter / X

Option A: Simple Connect (Recommended) ~1 minute

1. Go to My Agents → your agent → Integrations tab.
2. In the X (Twitter) card, click "Set Up" to open the setup wizard.

Step 1 — Connect your X account

1. Click "Connect X Account". A popup opens with the X authorization screen.
2. Log in to X (if needed) and click "Authorize app".
3. The popup closes automatically and the wizard shows your connected username (e.g. @YourHandle).

Step 2 — Define your content strategy

Tell the agent what to post about. You can pick a preset or write your own strategy:

• Brand Awareness — industry insights, tips, and thought leadership
• Product Updates — announcements, features, and behind-the-scenes
• Community Engagement — questions, conversations, and user shout-outs
• Custom — write your own detailed content brief

The strategy you write here becomes part of the agent's system prompt and is included in every scheduled post task, so the more detail you provide (tone, audience, topics to avoid), the better the results.

Step 3 — Pick a posting schedule

Choose how often the agent should post:

Click "Finish Setup" and you're done. The wizard creates a scheduled task and updates the agent's system prompt automatically.

Option B: Manual Setup (Advanced) ~5 minutes

What you'll need

Step 1 — Open the Developer Console

The API keys are not in your regular X/Twitter settings. You need the separate Developer Console.

1. Go to developer.x.com and sign in with your X account.
2. If this is your first time, you'll see a signup form. Enter an Account Name (e.g. "TamaleBot" or your brand name).

Step 2 — Describe your use case

X requires a short description of how you'll use the API. Here's what to write:

1. Paste the description above (or write your own) into the use case text box.
2. Check the box that says "You understand that you may not resell anything you receive via the X APIs."
3. Click Submit. Approval is usually instant for the free tier.

Step 3 — Get your API keys

After approval you'll land on the Developer Dashboard. It shows your usage, credits, and billing.

1. Click "Apps" in the left sidebar.
2. You should see a default app. Click on it to open its settings. If there is no app, click "Create App" and give it a name.
3. Go to the "Keys and tokens" tab inside your app.
4. Under Consumer Keys, click "Regenerate" to get your API Key and API Key Secret. Copy both immediately — the secret is only shown once.
5. Under Authentication Tokens, click "Generate" to create your Access Token and Access Token Secret. Copy both immediately.

Step 4 — Set permissions to Read and Write

By default, your app may only have Read permission. You need Read and Write to post tweets.

1. In your app settings, go to "User authentication settings" and click "Set up" or "Edit".
2. Under App permissions, select "Read and write".
3. For Type of App, select "Web App, Automated App or Bot".
4. Fill in the required Callback URL and Website URL. You can use your own website or https://tamalebot.com as a placeholder.
5. Click Save.

Step 5 — Add credits (pay-per-use)

X's API is pay-per-use. Posting is very cheap — about $0.01 per 10 tweets — but you need a positive credit balance or API calls will fail with a 403 Forbidden error.

1. In the Developer Console, click "Billing" in the left sidebar.
2. Click "Credits" and add a small amount. Even $5 will last months at typical posting volumes.
3. Optionally, enable auto-recharge so your bot never runs out mid-post.

Step 6 — Paste into TamaleBot

1. Open your agent's Settings → Integrations tab.
2. Paste all 4 keys into the Twitter/X fields:
   API Key API Key Secret Access Token Access Token Secret
3. Click Save. Your agent can now post, reply, and read mentions on X.

Troubleshooting

📸 Instagram ~1 minute

Option A: Simple Connect (Recommended) ~1 minute

Option B: Manual Setup (Advanced) ~10 minutes

What you'll need

1. You need a Facebook account and an Instagram Professional account (Business or Creator). If your Instagram is personal, open the Instagram app, go to Settings → Account → Switch to Professional Account and follow the prompts.
2. Go to developers.facebook.com and click "My Apps" in the top right, then click "Create App".
3. Choose the "Business" type. Give it any name you like, such as "My Social Bot".
4. On the app dashboard, find "Instagram Graph API" and click "Set Up".
5. Go to Tools → Graph API Explorer.
6. In the top dropdown, select your app.
7. Click "Generate Access Token". Log in with Facebook and grant the permissions it asks for.
8. Your User ID and Access Token will appear on screen. Copy both of them.
9. Paste the Access Token and User ID into TamaleBot — either in the Integrations tab (click the Instagram card).

🎬 TikTok ~1 minute

Option A: Simple Connect (Recommended) ~1 minute

Option B: Manual Setup (Advanced) ~15 minutes + app review

What you'll need

1. Go to developers.tiktok.com and create a developer account if you don't have one.
2. Click "Manage Apps" in the top menu, then click "Create App".
3. Under "Add Products", enable the "Content Posting API".
4. Fill out the app details and submit for review. TikTok typically reviews apps within a few business days. To avoid rejection:
   • Write a clear app description (e.g. "AI-powered social media assistant that creates and publishes content for my business").
   • Add an app icon and a privacy policy URL — TikTok requires one.
   • Make sure your TikTok account is a Business account, not a personal one.
5. Once your app is approved, go to your app's settings page and find the Access Token.
6. Paste the Access Token into TamaleBot — either in the Integrations tab (click the TikTok card).

▶️ YouTube ~1 minute

Option A: Simple Connect (Recommended) ~1 minute

Option B: Manual Setup (Advanced) ~10 minutes

What you'll need

1. Go to console.cloud.google.com and sign in with your Google account.
2. Create a new project (or select an existing one). Name it anything you like, such as "My Social Bot".
3. Go to "APIs & Services" → "Library" in the left sidebar.
4. Search for "YouTube Data API v3" and click "Enable".
5. Go to "APIs & Services" → "Credentials".
6. Click "Create Credentials" → "API Key". Copy the API key that appears.
7. Click "Create Credentials" → "OAuth Client ID".
8. If prompted to configure the OAuth consent screen, choose "External", add your email address, and save.
9. For Application Type, choose "Web application".
10. Under Authorized redirect URIs, add: https://developers.google.com/oauthplayground
11. Copy the Client ID and Client Secret that appear.
12. Go to developers.google.com/oauthplayground.
13. Click the gear icon (Settings) in the top right. Check "Use your own OAuth credentials" and paste your Client ID and Client Secret.
14. In the left panel, find "YouTube Data API v3", select all the scopes listed, then click "Authorize APIs".
15. Click "Exchange authorization code for tokens".
16. Copy the Refresh Token from the response.
17. Paste the API Key and Refresh Token into TamaleBot — either in the Integrations tab (click the YouTube card). The Integrations tab also accepts the Client ID and Client Secret. All four are required for uploading Shorts.

🔴 Facebook ~1 minute

Option A: Simple Connect (Recommended) ~1 minute

Option B: Manual Setup (Advanced) ~10 minutes

What you'll need

1. Go to developers.facebook.com, click "My Apps", and select your app (or create one if you haven't already).
2. Go to Settings → Basic in the left sidebar. Note your App ID and App Secret — you'll need them in a later step.
3. Go to Tools → Graph API Explorer.
4. In the "User or Page" dropdown at the top, make sure "User Token" is selected (not your Page).
5. Under "Permissions", add: pages_manage_posts, pages_read_engagement, and pages_show_list.
6. Click "Generate Access Token" and approve the permissions it asks for. This gives you a short-lived User Token (expires in ~1 hour).
7. Now exchange it for a long-lived User Token. In the Graph API Explorer, paste this into the query field and click Submit:
   GET /oauth/access_token?grant_type=fb_exchange_token&client_id={YOUR_APP_ID}&client_secret={YOUR_APP_SECRET}&fb_exchange_token={SHORT_LIVED_TOKEN}
   Replace the values in curly braces with your App ID, App Secret, and the token from the previous step. Copy the access_token from the response.
8. Finally, get your permanent Page Token. Paste this into the query field and click Submit:
   GET /me/accounts?access_token={LONG_LIVED_USER_TOKEN}
   Find your Page in the response. The access_token next to it is your permanent Page Token. Copy it.
9. Your Page ID is also in that same response, or you can find it in the URL when you visit your Facebook Page. Copy it.
10. Paste the Page Token and Page ID into TamaleBot — either in the Integrations tab (click the Facebook card).

💬 Threads ~1 minute

Option A: Simple Connect (Recommended) ~1 minute

Option B: Manual Setup (Advanced) ~5 minutes

What you'll need

1. If you set up Instagram above, you already have a Meta Developer app. If not, follow the first three Instagram steps to create one.
2. On your app dashboard, find "Threads API" and click "Set Up".
3. Go to Tools → Graph API Explorer.
4. Generate a token with Threads permissions selected.
5. Your User ID is the same as your Instagram User ID. Copy it.
6. Paste the Access Token and User ID into TamaleBot — either in the Integrations tab (click the Threads card).

🗨️ Slack ~1 minute

Option A: Simple Connect (Recommended) ~1 minute

Option B: Manual Setup (Advanced) ~5 minutes

What you'll need

1. Go to api.slack.com/apps and click "Create New App".
2. Choose "From scratch". Name it something like "TamaleBot" and select your workspace.
3. Go to "OAuth & Permissions" in the left sidebar.
4. Scroll down to "Bot Token Scopes" and add these scopes: chat:write, app_mentions:read, im:history, channels:history.
5. Scroll back up and click "Install to Workspace", then click "Allow".
6. Copy the "Bot User OAuth Token" (it starts with xoxb-). This is your Bot Token.
7. Now enable Socket Mode: go to "Socket Mode" in the left sidebar and toggle it on.
8. Slack will ask you to create an App-Level Token. Give it a name (e.g. "tamalebot-socket"), add the connections:write scope, and click "Generate".
9. Copy the token that appears (it starts with xapp-). This is your App Token.
10. Go to "Event Subscriptions" in the left sidebar and toggle it on. Under "Subscribe to bot events", add: app_mention and message.im.
11. Paste both tokens into TamaleBot — either in the Integrations tab (click the Slack card).

🎮 Discord ~1 minute

Option A: Simple Connect (Recommended) ~1 minute

Option B: Manual Setup (Advanced) ~5 minutes

What you'll need

1. Go to discord.com/developers/applications and click "New Application".
2. Name it something like "TamaleBot" and click Create.
3. Go to "Bot" in the left sidebar.
4. Click "Reset Token" and copy the token that appears.
5. Still on the Bot page, scroll down to "Privileged Gateway Intents" and enable "Message Content Intent".
6. Go to "OAuth2" → "URL Generator" in the left sidebar.
7. Check the "bot" scope. In the permissions that appear below, check "Send Messages" and "Read Messages/View Channels".
8. Copy the generated URL at the bottom of the page. Open it in your browser and invite the bot to your server.
9. Paste the bot token into TamaleBot — either in the Integrations tab (click the Discord card).

✈️ Telegram ~2 minutes

What you'll need

1. Open Telegram and search for @BotFather.
2. Send the command /newbot.
3. Choose a display name and a username for your bot (the username must end in "bot").
4. BotFather will reply with a token. Copy it.
5. Paste the token into TamaleBot — either in the Integrations tab (click the Telegram card).

✉️ Email (Gmail example) ~5 minutes

What you'll need

1. Go to myaccount.google.com and click "Security" in the left sidebar.
2. Make sure 2-Step Verification is turned on. If it's not, enable it first.
3. Go to myaccount.google.com/apppasswords.
4. Create an app password — select "Mail" and your device type.
5. Google will show a 16-character password. Copy it. This is your IMAP/SMTP password.
6. In TamaleBot, go to Integrations tab (click the Email card), and fill in:
   • IMAP Host: imap.gmail.com
   • Email / Username: your full email address (e.g. [email protected])
   • App Password: the 16-character app password you just copied
   • SMTP Host: smtp.gmail.com

🤖 OpenAI (for image generation) ~2 minutes

What you'll need

1. Go to platform.openai.com and sign in (or create a free account).
2. Click your profile icon in the top right, then click "API Keys" (or go directly to platform.openai.com/api-keys).
3. Click "Create new secret key". Give it any name you like.
4. Copy the key (it starts with sk-). You won't be able to see it again after closing this dialog.
5. Paste it into your agent's Integrations tab → OpenAI field.

📝 Notion ~3 minutes

What you'll need

1. Go to notion.so/my-integrations and sign in.
2. Click "New Integration".
3. Name it something like "TamaleBot" and select your workspace.
4. Click "Submit".
5. Copy the "Internal Integration Secret" (it starts with ntn_).
6. Paste it into your agent's Integrations tab → Notion field.
7. Important: In Notion, open the database or page you want the bot to access. Click the "..." menu in the top right, go to "Connections", find your integration name, and add it. The bot can only see pages you explicitly share with it.

🛒 Shopify ~5 minutes

What you'll need

1. Go to your Shopify Admin at yourstorename.myshopify.com/admin.
2. Go to Settings → Apps and Sales Channels → Develop Apps.
3. Click "Create an App" and name it anything you like.
4. Click "Configure Admin API scopes". Enable read/write access for Products, Orders, and Customers.
5. Click "Install App" and confirm when prompted.
6. Copy the "Admin API Access Token" (it starts with shpat_).
7. Your store domain is: yourstorename.myshopify.com
8. Paste both into your TamaleBot dashboard → Settings → Integrations → Shopify fields..

💳 Stripe ~2 minutes

What you'll need

1. Go to dashboard.stripe.com and sign in.
2. Click "Developers" in the sidebar (or top right corner).
3. Go to "API Keys".
4. Copy the "Secret key" (it starts with sk_live_ or sk_test_).
5. Paste it into your TamaleBot dashboard → Settings → Integrations → Stripe field..

📈 HubSpot ~1 minute

Option A: Simple Connect (Recommended) ~1 minute

Option B: Private App Token (Advanced) ~5 minutes

What you'll need

1. Go to app.hubspot.com and click the gear icon (Settings) in the top right.
2. Go to Integrations → Private Apps in the left sidebar.
3. Click "Create a Private App".
4. Name it something like "TamaleBot".
5. Go to the "Scopes" tab. Enable these scopes: crm.objects.contacts (read/write) and crm.objects.deals (read/write). Add others (companies, tickets, line items, products) as needed by the specialist you're using.
6. Click "Create App" and confirm.
7. Copy the Access Token (it starts with pat-).
8. Paste it into your TamaleBot dashboard → your agent → Integrations → HubSpot field.

🌏 Google Workspace ~15 minutes

This covers Gmail, Google Drive, Google Calendar, Google Docs, and Google Sheets — all in one setup.

What you'll need

1. Go to console.cloud.google.com and sign in.
2. Create a new project (or select an existing one).
3. Go to "APIs & Services" → "Library" in the left sidebar.
4. Search for and enable each of these APIs: Gmail API, Google Drive API, Google Calendar API, Google Docs API, and Google Sheets API.
5. Go to "APIs & Services" → "OAuth consent screen".
6. Choose "External", fill in your app name and email address, and save.
7. Go to "APIs & Services" → "Credentials".
8. Click "Create Credentials" → "OAuth Client ID".
9. For Application Type, choose "Web application".
10. Under Authorized redirect URIs, add: https://developers.google.com/oauthplayground
11. Copy the Client ID and Client Secret that appear.
12. Go to developers.google.com/oauthplayground.
13. Click the gear icon in the top right. Check "Use your own OAuth credentials" and paste your Client ID and Client Secret.
14. In the left panel, select the scopes for Gmail, Drive, Calendar, Docs, and Sheets.
15. Click "Authorize APIs", sign in with your Google account, and grant access.
16. Click "Exchange authorization code for tokens".
17. Copy the Refresh Token from the response.
18. Paste the Client ID, Client Secret, and Refresh Token into your agent's Integrations tab → Google Workspace fields.

🌐 Tailscale (private network access) ~5 minutes

Tailscale puts your TamaleBot agent on the same private network as your servers, so it can SSH into your 192.168.x.x, 10.0.0.x, home-lab, office VLAN, or cloud-VPC machines. Required for any SSH-enabled agent managing infrastructure that isn't on the public internet.

What you'll need

1. Sign up for Tailscale at login.tailscale.com/start. Free tier is fine to start.
2. Install Tailscale on your servers (the ones your agent will manage). One-liner from tailscale.com/download for each OS. Run sudo tailscale up on each server — they'll show up in your Tailscale admin panel. (one-time per server)
3. Create an auth key for the agent. Go to tailscale.com/admin/settings/keys and click "Generate auth key". Check these two options:
   • Reusable — so if the agent container restarts, it can reconnect.
   • Ephemeral — so old agent devices auto-cleanup when they disconnect. Stops "ghost device" accumulation.
4. Copy the key (starts with tskey-auth-).
5. Paste it into TamaleBot. Open your agent's dashboard → Integrations → Tailscale card. Paste the key, click Save.
6. The agent will join your tailnet on its next boot. You'll see a device named tb-<your-agent-name> appear at tailscale.com/admin/machines within 10–30 seconds.

Verify it worked

In the agent's chat window, ask:

You should see a list of every device on your tailnet, including the agent itself. If the list is empty or says "Logged out", check the Tailscale logs:

Security model

• The auth key is stored encrypted in your agent's config (AES-256-GCM). Only the agent container can decrypt it.
• The agent appears on your tailnet as a normal device. You can see it, revoke it, and scope its access in the Tailscale admin panel just like any other device.
• HTTPS interception is auto-disabled when Tailscale is on, because Tailscale's control-plane protocol requires raw TLS. Side effect: other outbound credential-injection (for OAuth integrations) won't work on this agent — use a BYOK/API-key path instead, or keep those integrations on a separate non-Tailscale agent.
• Outbound network restrictions are relaxed because the agent must reach arbitrary tailnet peers. If you need both a locked-down allowlist and Tailscale, reach out — we'll help.

Advanced: Tailscale SSH for fleets

If you're managing 20+ servers, skip per-server SSH key installs. Enable Tailscale SSH on each server and use one ACL in Tailscale admin to grant the agent access everywhere at once.

1. On each managed server (one-time): sudo tailscale up --ssh --accept-routes
2. In your Tailscale admin ACL, add:

   "tagOwners": {
     "tag:tamalebot-agent": ["autogroup:admin"],
     "tag:managed-server":  ["autogroup:admin"]
   },
   "ssh": [{
     "action": "accept",
     "src":    ["tag:tamalebot-agent"],
     "dst":    ["tag:managed-server"],
     "users":  ["root", "admin"]
   }]

3. Generate the Tailscale auth key with tag:tamalebot-agent attached, and tag your servers tag:managed-server in the admin panel.
4. That's it — the agent can now SSH to any tagged server with no per-server key install. Revoke by editing the ACL; it takes effect instantly across every device.

Tips

• Name things clearly. Rename your tailnet devices (office-web-1, home-nas, etc.) at admin/machines. The agent uses these names via MagicDNS.
• Keep the auth key for re-use. Reusable auth keys let multiple agents join the same tailnet with the same key, and survive container restarts.
• Can't reach a server? Ask the agent: "ping <hostname> from my end and show me the result." The agent uses tailscale ping which tells you if the connection path is working.

🔑 SSH Key (persistent agent identity) ~5 minutes

Gives an SSH-enabled agent a stable SSH keypair so it can log into your servers the same way every time — even after container restarts, redeploys, or upgrades. Install the public key once on each server and the agent has access forever (until you remove it).

What you'll need

1. Open your agent's dashboard → Integrations → SSH Key card.
2. Click "Generate new ed25519 key". TamaleBot creates an OpenSSH-format keypair. The public key fills into the top textarea; the private key goes into the lower one.
   • Prefer your own key? Run ssh-keygen -t ed25519 -C tamalebot-agent -N "" locally and paste both into the textareas instead.
3. Click Save. The private key is encrypted at rest in the agent config and mounted to ~/.ssh/id_ed25519 inside the container on every boot.
4. Install the public key on each target server. Click "Copy install one-liner" to get a single bash command. Run it on each server via whatever access you have (existing SSH, HopToDesk, VNC, console). Example command:

   mkdir -p ~/.ssh && chmod 700 ~/.ssh && \
   echo 'ssh-ed25519 AAAA... tamalebot-agent' >> ~/.ssh/authorized_keys && \
   chmod 600 ~/.ssh/authorized_keys

5. Verify by asking the agent in chat: "SSH into <hostname> and run whoami."

First-time bootstrap — servers with no existing SSH access

If you don't already have SSH working to a server (for example, a home machine you only reach via RDP/VNC/HopToDesk), get in through whatever interface you have, open a terminal on the server's desktop, and run the install one-liner from step 4 there. That bootstraps the first SSH path. From then on, the agent (and you) can use SSH.

Give the agent sudo (optional but recommended)

Without sudo, the agent can read most diagnostics but can't restart services, read protected logs, or install packages — roughly 60% of real IT work. There are three ways to grant it:

1. Passwordless sudo (easiest). On each server, run:

   echo '<agent-user> ALL=(ALL) NOPASSWD: ALL' | sudo tee /etc/sudoers.d/tamalebot-agent
   sudo chmod 440 /etc/sudoers.d/tamalebot-agent

   Replace <agent-user> with the SSH user the agent uses (e.g. ops, ubuntu, m). This grants full root on that machine via the agent's SSH key — same trust level as giving someone root SSH access.
2. Narrower passwordless sudo (safer). Scope to only the commands the agent legitimately needs:

   ops ALL=(ALL) NOPASSWD: /usr/bin/systemctl, /usr/bin/journalctl, \
   /usr/bin/apt, /usr/bin/docker, /bin/cat /var/log/*

   Add or remove paths to fit your policy.
3. Tailscale SSH with root ACL. If you use the Tailscale SSH path, add "users": ["root"] to your ACL. The agent logs in as root directly, no sudo needed.

Rotating or revoking the key

• Rotate: Click "Regenerate" in the SSH Key card, Save, then install the new pubkey on every server (remove the old line from authorized_keys). Takes a few minutes depending on fleet size — use the Tailscale SSH path if this gets painful.
• Revoke (emergency): Delete the matching line from ~/.ssh/authorized_keys on each server. The agent is locked out instantly without touching TamaleBot at all — your own SSH access is unaffected.

Security model

• Private key stored encrypted in the agent config (AES-256-GCM), never logged, never returned in API responses.
• Mounted at /home/agentuser/.ssh/id_ed25519 with 0600 perms at container boot, then the env-var carrying the key is unset so the agent process can't dump it via env.
• Separate from your personal keys. Always generate a dedicated key per agent — never paste in your own laptop's key. Scope and revocation become simple.

Features

📚 Knowledge Base

The Knowledge Base is where you upload the documents your agent will use to answer questions. Think of it like giving your agent a library — it can only reference what you put in there.

How it works

1. You upload files to your agent's Knowledge Base in the dashboard.
2. When a user asks a question, your agent finds the most relevant files — even when the wording differs from what you wrote in the doc. "Refund policy" matches a doc called "return procedure." You don't have to think about keywords; your agent handles it.
3. Your agent reads the content and answers, citing the source document.
4. If the user needs the actual file, your agent can share it directly in the chat.

How your agent gets the most out of your KB

The Knowledge Base becomes more valuable the more you put in. A few things to know:

• Your agent will tell you what it needs. On the first conversation, if the KB is empty or missing key files, your agent introduces itself and tells you specifically what to upload for best results. Sales will ask for pricing and battle cards; support for FAQ and policy docs; a sysadmin for runbooks. No guessing.
• Your agent can write to its own KB. When your agent figures out a resolution that worked, or a workflow quirk, or a customer preference worth remembering, it saves a short note to a private per-agent folder. Future conversations benefit. You can review these notes anytime from the Knowledge Base tab.
• Your agent gets better every week. On a schedule, your agent reviews recent conversations and distills a playbook. Next week starts with those lessons loaded. See Weekly Reflection Cycles below.

How to upload files

1. Go to your TamaleBot dashboard and select your agent.
2. Click the Knowledge Base tab.
3. Drag and drop files into the upload zone, or click browse to select files.
4. Each file can be up to 25 MB.
5. After uploading, you can add a description and tags to each file to help the agent find it more easily.

Supported file types

What to upload for a customer support agent

The more relevant content you upload, the better your agent answers. Here's what works best:

Tips for a good knowledge base

• Use clear file names. The agent searches by file name, description, and tags. return-policy.pdf is much better than doc_final_v3.pdf.
• Add descriptions and tags. After uploading, click a file to add a description like "30-day return policy for all products" and tags like "returns, refunds, policy". This helps the agent find the right file faster.
• Keep docs up to date. If your pricing changes, upload the new version. The agent can only answer based on what's in the KB.
• Use markdown or plain text when possible. These are the fastest for the agent to read. PDFs and Word docs work too — text is extracted automatically — but simple formats are more reliable.
• One topic per file works best. A focused shipping-policy.md is better than a 50-page everything.pdf. The agent searches for relevant files first, so smaller, focused files get matched more accurately.
• Include the questions, not just the answers. If your FAQ doc includes "Q: How do I reset my password?" the agent can match that question directly. A doc that only says "Go to Settings > Reset" is harder to find.
• Test after uploading. Ask your agent the questions your customers ask. If it can't find the answer, the file might need a better name, description, or more detail.
• Storage included: 5 GB of Knowledge Base storage is included free with every account. KB is shared across all your agents, so you can upload a document once and have every agent reference it. For heavier document sets, you can upgrade to Pro (20 GB, $5/mo) or Business (100 GB, $15/mo) from your account page. Per-file max is 100 MB.

🧠 Memory & Storage Scope ~3 minutes

Each TamaleBot agent has three places it can store data. They differ in scope (who can read it), durability (how long it lives), and what you'd use them for. Understanding the differences saves you from "wait, why can't my new agent see this?" surprises.

The three kinds of storage

What this means in practice

• One agent's memory is NOT visible to another agent, even on the same account. Each agent has its own memory_save log. If you want a shared ledger across agents, use Team Storage.
• Knowledge Base uploads are per-agent too — if you upload your company handbook to agent A, agent B doesn't see it automatically. Upload to each agent that needs it (or use the same KB as you deploy similar agents).
• Team Storage is the one thing that's truly shared, and only between agents in the same team deploy. Two agents deployed separately have no shared storage — they can only coordinate if you explicitly deploy them together as a team.
• Nothing is shared across accounts. All three storage types are scoped to your account. Your agents and someone else's agents never see each other's data.

Which one should I use?

• Agent remembered something from a past conversation? That's memory_save. Use it for the agent's own running context.
• Multiple agents collaborating on a shared state? Team Storage. Deploy them as a team to get this automatically.
• Looking up reference material (docs, runbooks, policies)? Knowledge Base. Upload the files once; the agent queries them when needed.

📆 How Your Agent Gets Better Over Time ~2 minutes

Most chatbots reset every conversation. Your TamaleBot agent doesn't. On a weekly schedule, it reviews what it learned and distills a playbook it will pick up on next Monday — the same way a new hire gets better over their first three months on the job.

What this means for you

• Your corrections stick. Tell your agent once: "we don't say 'reach out' in emails." It's remembered permanently, not just for this conversation.
• Your agent compounds. An agent running for three months has three months of distilled lessons loaded. New conversations start with that context.
• Your knowledge stays yours. The playbooks your agent writes live in your private Knowledge Base, derived from your team's actual conversations. They don't exist anywhere else.

Which agents do this

Most of your hires run reflection on their own schedule: Danny (sales), Maya (support), Aria (data analyst), Priya (exec assistant), Zoe (social media), Iris (legal), Naomi (HR), Dean (accounting), and Aviv (technical advisor). You can see and manage each agent's schedule from the dashboard.

Managing your agent's learning

• See what it's learned. Open the Training tab on your agent's dashboard page. It shows the summarized lessons your agent has saved — corrections, preferences, recurring patterns, and weekly reflection playbooks. The full reflection notes also live in your Knowledge Base tagged reflection with the week's date.
• Pause it. If your agent is still new and the KB is sparse, you can pause reflection from the Schedules tab until you've had a chance to upload your core documents.
• Steer it. You can edit the reflection question for a specific agent if you want it focusing on something different — e.g. asking a support agent to focus on escalation patterns instead of general tickets.

👥 Sub-Agents: In-Conversation Helpers ~5 minutes

Any one of your agents can spin up a short-lived helper to handle a specific subtask, then fold the result back into its own work. The helper — a sub-agent — lives entirely inside the parent agent; you never hire it, and it never shows up on your dashboard.

How sub-agents work

The agent decides at runtime to spawn a helper for a specific task. The sub-agent lives only long enough to complete the task, inherits the parent's config and credentials, and is gone when it returns the result.

• How: Sub-Agents are bundled with every packaged-specialist subscription — no add-on toggle. The parent agent uses the sub_agent tool whenever it decides to delegate.
• Lifecycle: Ephemeral. Spawned when needed, executes one task, dies when done (max 5 minutes). Never appears on your dashboard.
• Storage: None of its own. Inherits the parent's API keys and LLM config. Anything it needs to persist must be returned to the parent, which can then memory_save it.
• Messaging: Parent uses sub_agent tool to send a task, awaits a single response. No peer-to-peer messaging.
• Billing: Runs against the parent agent's included LLM-token allowance — no new subscription, no separate dashboard entry.
• Constraint: Sub-agents cannot spawn their own sub-agents (no recursion — prevents runaway chains).
• Good fit: A specialist subtask inside one conversation — "delegate this research to a sub-agent with a tighter security policy," or "spawn a sub-agent to summarize these 10 URLs while I finish drafting."

When a sub-agent helps

• "I want one agent that can break up a complex task into parallel subtasks" → Sub-Agents.
• "I want my agent to occasionally delegate a focused subtask to a helper with a tighter security policy" → Sub-Agents.
• "I want to summarize a batch of documents without blocking the main conversation" → Sub-Agents.

Sharing state across agents

Sub-agents are stateless — they hand a result back to the parent and disappear. If you need two long-lived agents to collaborate on shared state across days or weeks, that's a different mechanism: deploy them together as a team so they share Team Storage (the team_storage_* tools) and can message each other via message_agent. See Memory & Storage Scope for how team storage differs from per-agent memory.

💬 Chat Widget

The Chat Widget lets you embed a customer-facing AI chat on your website. Your visitors see a chat bubble in the corner of your site. When they click it, they can ask questions and get instant answers from your agent.

How it works

1. When you deploy an agent, choose "Website Widget" or "Both" as the deployment mode.
2. After deployment, you get a one-line embed code to paste into your website.
3. The widget loads as a chat bubble in the bottom-right (or left) corner of your site.
4. Visitors click the bubble, type a question, and get a response from your agent.
5. Conversations are stored per-session so visitors can refresh the page and continue where they left off.

Embed code

Add this line to your website, just before </body>:

Replace your-agent-name with the name you chose when deploying.

Customization options

Works everywhere

The widget is a single JavaScript file with no dependencies. It works on any website:

• Static HTML sites
• WordPress, Squarespace, Wix, Webflow
• Shopify storefronts
• React, Next.js, Vue, Angular apps
• Any site where you can add a <script> tag

Security & isolation

• Shadow DOM — the widget's styles are completely isolated from your site. It won't break your layout or CSS.
• Rate limiting — 20 messages per hour per visitor, plus a configurable daily conversation cap to prevent abuse.
• Anonymous sessions — visitors don't need to log in. Sessions are tracked via a token stored in the browser and expire after 24 hours.
• No cookies — the widget uses localStorage, not cookies. No cookie banner needed.

Billing

Widget conversations are billed to the agent owner's account at the same per-message rate as any other channel (Slack, Discord, etc.). There is no extra charge for the widget itself. See the Customer Support pricing section for estimated costs by volume.

🧩 Agent Skills ~3 minutes

Agent Skills are reusable capability packages that extend what your agent can do. Instead of writing long system prompts for every task, you can add pre-built skills from community marketplaces — things like customer onboarding workflows, sales objection handling, data analysis templates, and more.

How it works

1. During deployment, open the 3. Agent Skills section in the configure step.
2. Type a keyword in the search bar (e.g. "customer support", "writing", "research"). Results appear from community skill marketplaces.
3. Click a skill to add it. It appears as a chip below the search bar. Add as many as you need.
4. Alternatively, paste a GitHub URL directly into the search bar to add a custom skill from any public repository.
5. Deploy your agent. Skills are automatically pulled into the agent container and available at startup.

Verified vs. unverified skills

Skills can be cryptographically signed by their authors using Ed25519 signatures. In the deploy wizard and agent dashboard, you'll see:

• ✅ Verified — The skill has a valid Ed25519 signature from the author. The contents haven't been tampered with since signing.
• ⚠️ Unverified — No signature found, or the signature didn't match. The skill may still work fine, but you should review its instructions before deploying.

Skill format

Each skill is a directory containing a SKILL.md file with YAML frontmatter:

---
name: Customer Onboarding
description: Structured onboarding workflow for new customers
---

When a user says they are a new customer, follow these steps:
1. Greet them and ask for their company name...
2. Walk them through account setup...
...

Your agent loads skill names and descriptions at startup (lightweight), then reads the full instructions on-demand when a user's request matches a skill.

🛡️ Custom Security Policies Advanced / Developer

By default, every TamaleBot agent runs with a built-in security policy that blocks dangerous commands, sensitive file access, and data exfiltration. For advanced users, you can define custom policies in YAML to tighten or loosen rules for your specific use case.

How it works

Every tool call your agent makes — shell commands, file reads, HTTP requests, SSH, Git, browser actions — passes through the policy engine before execution. The engine checks the action against your rules and either allows it (with an audit log entry) or blocks it immediately.

Writing a custom policy

Create a YAML file with any combination of these fields:

# my-policy.yaml
name: strict-finance

blocked_read_paths:
  - /etc/shadow
  - /etc/passwd
  - ~/.ssh/
  - ~/.aws/credentials
  - .env

blocked_write_paths:
  - /etc/
  - /usr/bin/
  - /sys/

dangerous_command_patterns:
  # Block database destruction
  - 'DROP\s+TABLE'
  - 'DROP\s+DATABASE'
  - 'TRUNCATE\s+TABLE'
  # Block filesystem destruction
  - 'rm\s+-rf\s+/'
  - 'sudo\s+rm'
  # Block exfiltration
  - 'curl.*pastebin'
  - 'curl.*webhook\.site'
  # Custom: block crypto wallet operations
  - 'solana\s+transfer'
  - 'eth\s+send'

# Restrict outbound HTTP to specific domains
allowed_domains:
  - api.anthropic.com
  - api.stripe.com
  - your-internal-api.com

# Restrict SSH access
allowed_ssh_hosts:
  - deploy.yourcompany.com

# Restrict Git operations
allowed_git_repos:
  - github.com/your-org

max_requests_per_minute: 30

Deploying with a custom policy

Set the TAMALEBOT_POLICY_FILE environment variable to point to your YAML file:

TAMALEBOT_POLICY_FILE=/app/config/my-policy.yaml

You can include the YAML file in your agent's knowledge base or mount it into the container. Environment variable overrides (like TAMALEBOT_ALLOWED_SSH_HOSTS) always take precedence over YAML values, so you can use YAML as a base and override specific fields per deployment.

Default policy

If no custom policy file is specified, agents use the built-in default policy which blocks:

• Sensitive file reads (SSH keys, AWS credentials, .env files, Docker/Kube configs)
• System directory writes (/etc/, /usr/bin/, /boot/, /proc/)
• Dangerous commands (DROP TABLE, rm -rf /, chmod 777, fork bombs)
• Data exfiltration (curl to pastebin, ngrok, webhook.site, etc.)
• Homoglyph/IDN domain attacks (mixed Unicode scripts in URLs)

🔐 Skill Signing (Ed25519) Advanced / Developer

Skill signing lets authors cryptographically prove that a skill hasn't been tampered with. TamaleBot uses Ed25519 signatures — the same algorithm used by SSH, GPG, and most modern signing systems. This is optional: unsigned skills still work, but verified skills get a trust badge in the deploy wizard and dashboard.

For skill authors: signing your skill

1. Generate a keypair (one time):

   node -e "
     const ed = require('@noble/ed25519');
     const priv = ed.utils.randomPrivateKey();
     const pub = Buffer.from(ed.getPublicKey(priv)).toString('hex');
     console.log('Private:', Buffer.from(priv).toString('hex'));
     console.log('Public:', pub);
   "

   Save both keys somewhere safe. The private key is used to sign; the public key is published with your skill.

2. Sign your SKILL.md:

   node -e "
     const ed = require('@noble/ed25519');
     const fs = require('fs');
     const content = fs.readFileSync('SKILL.md');
     const priv = 'YOUR_PRIVATE_KEY_HEX';
     ed.sign(content, priv).then(sig =>
       fs.writeFileSync('SKILL.md.sig', Buffer.from(sig).toString('hex'))
     );
   "

3. Save your public key:

   echo "YOUR_PUBLIC_KEY_HEX" > SKILL.md.pub

4. Publish all three files in your skill directory:

   my-skill/
     SKILL.md        # The skill instructions
     SKILL.md.sig    # 128-char hex Ed25519 signature
     SKILL.md.pub    # 64-char hex Ed25519 public key

For users: what verification means

When your agent loads a skill at startup, TamaleBot automatically checks for .sig and .pub files. If found and valid, the skill is marked as verified in the system prompt and dashboard. Verification confirms:

• The SKILL.md file hasn't been modified since the author signed it
• The signature was created by someone who holds the private key matching the published public key

It does not confirm the author's real-world identity — for that, check the author's public key against their GitHub profile or marketplace listing.