# Talkable invite program

Set up, test, and run invites in your product.

## Overview

Talkable gives your product an invite program: personal links and codes for your users, a configurable invite allowance, and a record of who invited each new signup.

Your agent connects the program to your product. Talkable runs the campaign behind it. You keep your product, its user accounts, and the experience you ship.

The invite program is free to start. Use your existing coding agent and hosting; their usual pricing applies.

## Set up with your agent

Open your product’s codebase in your coding agent. It needs access to your code, web instructions, and a terminal.

Your product needs:

- User accounts with an email address. The invite block shows only to a signed-in user.
- A backend that keeps the private API key of Talkable. The backend signs the email of the signed-in user with it. The key must never get to the browser.
- Backend code that runs at each signup, for example your signup handler or a hook of your auth library. There, your backend sends the invite code to Talkable.

Add a Talkable invite program to this product. Follow https://www.talkable.com/skill.md.

The homepage shows the short request; its Copy prompt button includes the setup-instructions URL above.

The prompt loads [Talkable’s current setup instructions](https://www.talkable.com/skill.md). Your agent creates a sandbox, builds the integration, and returns a preview for you to review.

A sandbox is a temporary invite program in Talkable, in test mode. You need no Talkable account for it. To keep the program, you claim it: Talkable emails you a link, and you confirm on the claim page. Talkable deletes an unclaimed sandbox after 14 days with no use.

## Quick start

- Give your agent the prompt above. It reads your project’s brand, signup flow, and configuration.
- Review the preview in your product. Check the copy, the invite allowance, and where an invitation sends a friend.
- Test a signup with an invite code. Confirm the accepted invite and the change in allowance.
- Give your agent your email for the claim. Open the emailed link and confirm on the claim page. Then approve the launch and deploy the integration.

Keep the same sandbox for the same product and environment. If setup has already started, ask your agent to continue it using the [current instructions](https://www.talkable.com/skill.md).

## How the invite program works

Invites turn a recommendation into a way to join your product. New members can invite others too, so the channel can grow with your community. Use the prebuilt program with open signup or require an invite to join; your agent connects the policy you choose.

Each environment of your product has one invite-only campaign in Talkable. “Invite-only” is the name of this Talkable campaign type. It does not mean that people need an invite to join your product. The Talkable AI assistant builds it from a brief that your agent writes. Talkable keeps the copy and the brand of the invite block and the number of invites for each user. It also keeps the layout of the block and the URL of your signup page. These values live in Talkable, not in the code of your product.

**The invite block**: Your agent puts the block on 2 or 3 pages that signed-in users see, for example the dashboard and the account page. The block shows the invite link and code of the user, buttons for X, LinkedIn, WhatsApp, Facebook and email, and the number of invites left.

**Personal invitations**: Each eligible user gets an invite link and code. A friend can arrive through the link or enter the code at signup.

**The friend’s signup**: The invite link opens your signup page, with the code in the `invite` parameter. Your backend sends the code to Talkable. If Talkable answers `ok`, the signup continues.

**Invite allowance**: Choose how many people a user can invite. An accepted invitation uses one invite; copying or sharing a link does not.

**Attribution**: An accepted invite connects the new signup to the person who invited them.

**The next invitation**: Show the invite block to eligible new members too, so they can invite someone of their own.

**Test mode and launch**: Until the launch, the campaign is in test mode. Only a preview URL with the campaign ID shows the block. After the launch, each signed-in user sees the block.

## Architecture

Three parties do the setup. Your coding agent changes only the code of your product. The Talkable AI assistant builds the campaign in Talkable. You approve the claim and the launch.

**Setup in development**

| Step | Who | What happens |
| --- | --- | --- |
| Sandbox | Your agent | Makes a sandbox with one API call. You need no Talkable account and no API key. |
| Campaign | Talkable AI assistant | Builds the brand, one invite-only campaign, its copy and the page where friends land. Your agent writes the brief: the product name, the URLs, the brand, the tone and the invites per user. The campaign stays in test mode. |
| Integration | Your agent | Adds the invite block to 2 or 3 pages for signed-in users, and the invite check to signup. |
| Test | Your agent and you | Previews the block and tests one invite. Launch needs one test invite that gets `ok`. |
| Claim | You | Open the emailed link and press the button. The program goes into your Talkable account. |
| Launch | Your agent | Makes the campaign live after your yes in the chat. |

Staging, if your product has it, and production get their own sandboxes. Each sandbox is a separate Talkable site. Your agent writes a brief for each environment. You claim each sandbox with the email of the development claim, so all the sites go into one account. Put the Site ID and the private API key of each site into the secrets of its environment. Then deploy the product, and your agent tests one invite and launches after your yes.

## Connect it to your product

The integration has two parts: an invite block for signed-in users and a server-side check in your signup flow.

### The invite block

Your backend signs the authenticated user’s identity. The page loads Talkable’s invite block with that identity and your Site ID. Keep the private API key on the server.

- `email`: the email of the signed-in user, in lowercase. Never sign an email from a request.
- `signed_at`: the current Unix time in seconds. Talkable accepts a value from 1 day old to 5 minutes in the future.
- `signature`: HMAC-SHA256 of `invite-only:v1:EMAIL:SIGNED_AT` with the private API key, in lowercase hex.

Talkable closes a block that has no valid signature.

### The signup check

Keep the incoming `invite` query parameter through the signup form. Call Talkable from your backend at the time that fits your signup policy:

- If signup requires an invite, call after your product’s own checks pass, just before you create the account. A refused signup then uses no invite.
- If anyone can sign up, call when you create the account. If your product requires email confirmation, call when the friend confirms the email instead, so that an unconfirmed email uses no invite.

```
POST https://www.talkable.com/api/v2/invite_redemptions
Authorization: Bearer TALKABLE_PRIVATE_API_KEY
Content-Type: application/json

{
  "site_slug": "TALKABLE_SITE_ID",
  "code": "INVITE_CODE",
  "email": "FRIEND_EMAIL",
  "ip_address": "FRIEND_IP"
}
```

The `ip_address` field is optional.

**Redemption responses**

| Status | What your product does |
| --- | --- |
| `ok` | Continue the signup. Repeating the same code and email records no extra redemption. |
| `invalid` | Show a helpful message. If your product requires an invite, ask for a valid code. |
| `used_up` | Explain that this invitation’s allowance has been used. Follow your product’s signup policy. |

The [public skill](https://www.talkable.com/skill.md) contains the complete identity-signing and integration examples. Your agent should read it before implementing this flow.

## Keys and security

The setup uses three keys and one public ID. Keep each key out of git, logs, the chat and the browser.

**Keys and IDs**

| Key | Who uses it | Where it lives |
| --- | --- | --- |
| Sandbox key | Your agent, before the claim: the AI assistant, the claim link and the claim. | A file that only your user can read, in `~/.config/talkable/sandboxes/`. The key stops at the claim. |
| Owner key | Your agent, after the claim: the launch and later changes. | The same file. Talkable gives this key one time. |
| Private API key | Your backend: the signature of the invite block and the redemption call. | `TALKABLE_PRIVATE_API_KEY`. In development, an env file that git ignores. In staging and production, the secrets of the environment. |
| Site ID | The page and your backend. | `TALKABLE_SITE_ID`, in the same place as the private API key. Each environment has its own Site ID. It is not a secret. |

The browser gets only the Site ID, the email of the user, `signed_at` and the signature. Talkable refuses a redemption call from a browser.

Before the claim, the sandbox is in test mode. It cannot launch, send emails or add users.

## Preview and test

Ask your agent for clickable previews in your product. Review both the signed-in user’s invite block and the friend’s signup journey.

- Open the invite block as a test user. Confirm the brand, copy, and allowance.
- Copy the code and open signup as a second user. Complete a signup with a different email.
- Confirm that the first user has one fewer invite and the accepted invite is attributed correctly.
- Check that the new user can access their own invite block. Test an invalid code, a repeated request, and the completed-allowance state.

**Testing before you claim**

Use the code on your local signup page. Invite links and social sharing become available after claiming. A local preview needs the campaign ID in its URL; public development hosts may require claiming before the preview works.

## Claim and launch

The claim moves the sandbox into your Talkable account. The launch makes the campaign live. Your agent asks you before each step.

### Claim the program

1. Your agent asks for your email and shows it to you. The person who opens the link gets the program, so make sure that the email is correct.
2. Talkable emails you a claim link. The link works once, within 24 hours.
3. Open the link and press the button on the claim page. Only the button claims the program. A mail scanner that opens the link changes nothing.
4. Your agent checks the claim status every 10 seconds. After you confirm, it continues the setup.

**The claim page**

| Your email | What the page does |
| --- | --- |
| Has no Talkable account | “Take over” creates an account for the email and signs you in. The button also accepts the Terms. The account has no password. To set one, use “Forgot password” on the login page. |
| Has a Talkable account | Sign in first. Then “Move into my account” moves the program into that account. |
| Has an account that is not eligible | The page has no button and explains why. See [Limits and troubleshooting](#limits-and-troubleshooting). |
| Differs from your signed-in account | The page shows only a “Sign out” button. Sign out, then open the link again. |

After you confirm, your agent gets one of two states:

- `claimed`: your agent gets the owner key and the Site ID. It can launch the campaign.
- `moved`: the program moved into your account, and your agent got no key. Copy the new private API key from the “API integration” page of the site in Talkable. In development, put it into the env file in place of the old key. In staging and production, put it into the secrets of the environment. Do not paste it into the chat. Then test one invite, and launch the campaign in Talkable.

### Launch

- Your agent launches only after your yes in the chat.
- Development can launch on `localhost`, a `*.localhost` name or `127.0.0.1`. Launch refuses `example.com`, `.local` and `.test` names, and other IP addresses.
- Each environment gets its own site. Your agent sends the claim links of staging and production to the email of the development claim, so the sites go into one account.
- Launch deletes the test offers and referrals in Talkable. It also deletes the signup events of test friends with QA emails, for example on `example.com`. The user accounts in your product do not change.

### Before you approve the launch

- Examine the site and signup URLs of this environment, the invitation copy, Terms and Privacy links, and social sharing image.
- Complete a successful test redemption and review both sides of the invite journey.
- Confirm the exact campaign and account before approving launch.
- Deploy the integration with TALKABLE_SITE_ID and the private key in server-side configuration.

After the deploy, look at the live experience again.

## API reference

The base URL is `https://www.talkable.com/api/v2`. Send the key as `Authorization: Bearer KEY`. Your agent also sends `X-Talkable-Client` with its name, for example `claude-code`.

Each answer is JSON: `{"ok": true, "result": {...}}` or `{"ok": false, "error_message": "..."}`. The errors in the “Error codes” list below also have `error_code`. Other errors, for example the errors of `/invite_redemptions`, have only `error_message`.

- `POST /agent/sandboxes`: Makes a sandbox. It needs no key and no body. The answer is HTTP 201 with `api_key` (the sandbox key), `site_slug` (the Site ID), `private_api_key` and `mcp_url`.
- `POST /agent/sandbox/claim_link`: Sends the claim link to `email`. Key: the sandbox key. The answer has `expires_in`: 86400 seconds.
- `POST /agent/sandbox/claim`: Gives the state of the claim in `status`: `pending`, `claimed` or `moved`. Key: the sandbox key. For staging and production, the body has `owner_key`: the owner key of the development claim.
- `POST /agent/sandbox/launch`: Launches the campaign `campaign_id`. Key: the owner key.
- `POST /invite_redemptions`: Records an invite at signup. Key: the private API key, from your backend only. The body has `site_slug`, `code`, `email` and the optional `ip_address`. The answer has `status`: `ok`, `invalid` or `used_up`.

### Error codes

- `unauthorized` (HTTP 401): the key is wrong, or the sandbox has an owner already. Use the key of the current step.
- `rate_limited` (HTTP 429): wait for the seconds in `Retry-After`, then try again.
- `rate_limit_unavailable` and `paused` (HTTP 503): try again later.
- `invalid_email` (HTTP 422): send one plain ASCII email address.
- `link_expired` (HTTP 422): no claim link is live. Send a new link.
- `campaign_not_found` (HTTP 404): use the ID of the invite-only campaign.
- `not_invite_only` and `not_in_test_mode` (HTTP 422): launch only the invite-only campaign, and only in test mode.
- `url_not_production` (HTTP 422): set the site URL and the signup URL of this environment.
- `no_invite_code` (HTTP 422): put the invite code back into the link for friends.
- `no_test_redemption` (HTTP 422): test one invite, then launch again.
- `campaign_invalid` (HTTP 422): send `error_message` to the AI assistant as a fix.

The AI assistant works through the campaign tools: JSON-RPC over HTTP at the `mcp_url` of the sandbox. The setup uses three tools: `prompt_ai_assistant`, `check_ai_assistant_run` and `list_campaigns`.

The [OpenAPI file](https://www.talkable.com/api-docs/invite-program/openapi.yaml) describes the same calls.

## Keep working with your agent

After setup, connect your agent to [Talkable’s MCP server](https://www.talkable.com/mcp) to work with your program in conversation. The server supports reporting, campaign and account lookups, product questions, and support tools. Available actions depend on your site’s enabled capabilities, your role and the connection’s scopes.

- Ask which invitations resulted in signups, with a campaign and time period.
- Look up a person or referral to investigate an invitation.
- Ask how the program works and get answers grounded in Talkable’s product documentation.

Use [Talkable’s MCP connection guide](https://docs.talkable.com/mcp_server/getting_started/) for authentication and client setup. The [reporting and support guide](https://docs.talkable.com/ai/reporting_and_support/) describes the tools and their role requirements. Connecting MCP is a separate authenticated connection; copying the setup prompt does not install it automatically.

### Changes after launch

The current invite-program instructions allow the assistant to change branding after launch. Other changes to a live program require the owner to act in Talkable. Before launch, ask your agent to adjust the copy, appearance, allowance and signup destination through Talkable. Follow the [current invite-program instructions](https://www.talkable.com/skill.md) for the exact supported workflow.

## Reference for agents

Start with `skill.md`. It tells your agent the setup steps, the integration, the tests and the approvals. The old URL, `https://www.talkable.com/api/v2/agent/skill.md`, still works.

- [skill.md](https://www.talkable.com/skill.md): Setup instructions for coding agents
- [llms.txt](https://www.talkable.com/llms.txt): Index of the agent files
- [agent-skills/index.json](https://www.talkable.com/.well-known/agent-skills/index.json): Agent Skills index, version 0.2.0
- [skills/index.json](https://www.talkable.com/.well-known/skills/index.json): Agent Skills index, version 0.1.0
- [openapi.yaml](https://www.talkable.com/api-docs/invite-program/openapi.yaml): The API as OpenAPI
- [api-docs](https://www.talkable.com/api-docs): Swagger UI of the Talkable API
- [mcp](https://www.talkable.com/mcp): Talkable MCP server

This documentation as text:

- [docs.md](docs.md): This page
- [llms.txt](llms.txt): Index of this documentation
- [llms-full.txt](llms-full.txt): Complete context

Load only the context needed for the task. Reuse the product’s existing campaign context and keep private credentials on the backend.

## Limits and troubleshooting

**Limits**

| Limit | Value |
| --- | --- |
| Redemption calls | 120 a minute for each site. Above that, Talkable answers HTTP 429 with `Retry-After: 60` and no `error_code`. |
| Claim link | Works for 24 hours and one time. |
| Claim links | 3 an hour for each sandbox, and 4 an hour for each email. |
| Assistant runs | 10 for each sandbox before the claim. The claim gives more runs. |
| Test advocates | 50 for each sandbox before the claim. After that, the block does not show until the claim. |
| Unclaimed sandbox | Talkable deletes it after 14 days with no use. |

### Redemption requests

The current limit is 120 calls per minute per site. A rate-limited request returns HTTP 429 and `Retry-After: 60`. Do not repeatedly retry within a signup request. Follow the public skill’s behavior for open signup versus invite-required signup.

### If the preview is empty

Check the signed-in identity, the preview URL’s campaign ID, and the development host. Before claiming, the block is available on localhost or a private IP; public development hosts need the claim step first. The public skill also explains the required development Referrer-Policy.

### If the email already has a Talkable account

If the account is eligible to claim the program, sign in, then press the button on the claim page. If it is not eligible, for example an account with 2FA or SSO, the claim page has no button. Give your agent another email, or ask support@talkable.com to move the program into your account. If your account cannot claim the program for another reason, the claim page explains why. Then ask support@talkable.com for help.

### If the claim link does not work

A link works for 24 hours and one time. Ask your agent for a new link. A new link stops the earlier link. Use the link in the newest email. Each sandbox gets 3 links an hour, and each email gets 4. If the email does not come, look in your spam folder before you ask for a new link.

### If launch needs another step

`url_not_production` means that the site URL is not a real URL of this environment. For example, it is `example.com`, a `.local` or `.test` name, or an IP address other than `127.0.0.1`. `no_test_redemption` means a successful test invite is still needed. Ask your agent to report the exact error and the next action.

Use the [current public instructions](https://www.talkable.com/skill.md) for the full sandbox limits and recovery steps.