Talkable invite program

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.

The homepage shows the short request. Its Copy prompt button also includes the setup-instructions URL shown above, so your agent can follow the complete workflow.

The prompt loads Talkable’s current setup instructions. 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#

1. Give your agent the prompt above. It reads your project’s brand, signup flow, and configuration.
2. Review the preview in your product. Check the copy, the invite allowance, and where an invitation sends a friend.
3. Test a signup with an invite code. Confirm the accepted invite and the change in allowance.
4. 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.

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.

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.

The public skill 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.

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.

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

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.

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 describes the same calls.

Keep working with your agent#

After setup, connect your agent to Talkable’s MCP server 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 for authentication and client setup. The reporting and support guide 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 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.

This documentation as text:

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#

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 for the full sandbox limits and recovery steps.