canonical: https://jentic.com/apis/impactapp.com.au/talkbox

# Impactapp TalkBox API

TalkBox is a customer engagement platform that drives email, SMS, and marketing automation campaigns for retail and hospitality brands. The API exposes 59 endpoints covering contacts, custom fields, tags, promotions, vouchers, offers, surveys, and email and SMS templates. Agents can segment audiences, trigger resubscription flows, issue vouchers, and pull engagement data without touching the TalkBox dashboard. The service uses HTTP Basic authentication with a username and API password issued from the TalkBox account.

## For AI agents

Manage TalkBox contacts, tags, vouchers, offers, surveys, and email or SMS templates programmatically. Useful for resubscription, segmentation, and loyalty workflows.

## Scope

Does not handle payment processing, point-of-sale transactions, or order management - use for marketing engagement, loyalty contacts, and voucher issuance only.

## Capabilities

- Create and update contact records with custom field values and tag assignments
- Trigger resubscription email or SMS flows for individual contacts
- Issue and revoke vouchers tied to specific promotions and offers
- Build segments by tag, field, or behaviour and pull contact lists for campaigns
- Publish and update email and SMS templates ready for scheduled sends
- Collect survey responses and pull aggregated answer data for reporting

## Use cases

### Loyalty Resubscription Campaigns

Re-engage lapsed retail customers by triggering resubscription emails or SMS through TalkBox. Use the contacts and tag endpoints to identify lapsed segments, then call the resubscription endpoints to send opt-in confirmations one contact at a time. The flow handles consent capture and reactivates marketing eligibility once the contact confirms.

Example prompt: List all contacts tagged 'lapsed-2025', then send a resubscription email to each contact and tag them as 'reengage-pending'.

### Promotion and Voucher Issuance

Run targeted promotions for hospitality and retail customers by combining the offer, promotion, and voucher endpoints. Agents can create a promotion, attach offers, and issue vouchers to a segmented contact list, then track redemption status through the voucher and contact endpoints.

Example prompt: Create a 20% off promotion, attach it to the 'Summer Drinks' offer, and issue a voucher to every contact tagged 'cocktail-club'.

### Survey Collection for CX Teams

Power post-visit feedback loops by deploying surveys and collecting responses through TalkBox. Agents can list surveys, retrieve question definitions, and pull response data to feed into reporting tools or trigger follow-up actions for unhappy customers.

Example prompt: Pull responses from the 'February Cafe Visit' survey and tag any contact who scored below 3 with 'needs-followup'.

### Agent Engagement Console

Expose TalkBox to AI agents via Jentic so support and marketing agents can lookup contacts, tag segments, and dispatch resubscription messages from one chat surface. Agents resolve a contact by email, fetch tags and recent activity, and issue the right action without context-switching to the TalkBox UI.

Example prompt: Find the contact with email priya@example.com, list their current tags, and add the tag 'enrolled-march-promo' if not already present.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/contact` | Create a contact |
| POST | `/contact/create_or_update` | Create or update a contact by match key |
| GET | `/contact/find_first` | Find first contact by query |
| POST | `/contact/{id}/send_resubscription_email` | Send a resubscription email |
| POST | `/contact/{id}/send_resubscription_sms` | Send a resubscription SMS |
| GET | `/tags` | List tags used for segmentation |
| POST | `/tags` | Create a new tag |

## Key resources

- **Contacts** — Create, find, update, and tag customer profiles, plus trigger resubscription emails and SMS
- **Tags** — Manage tags used for segmentation across contacts, campaigns, and vouchers
- **Promotions and Vouchers** — Create promotions, attach offers, and issue or revoke vouchers tied to campaigns
- **Templates** — Manage reusable email and SMS templates referenced by scheduled sends
- **Surveys** — Retrieve survey definitions and collect responses for CX reporting
- **Custom Fields** — Define and update custom field schemas applied to contact records

## Why Jentic

- **Setup:** Wiring TalkBox by hand means encoding its Basic auth against the talkbox.impactapp.com.au host and finding the right operation among a large contact and engagement surface yourself. Through Jentic you install once, import the TalkBox API from the API Directory, store the credentials once, and your agent calls it.
- **Permission scoping:** TalkBox puts the contact id in the URL path (`/contact/{id}/send_resubscription_sms`, `/contact/{id}/send_resubscription_email`), so a rule can pin your agent to one contact. You choose the operations it may call, so a lookup-only agent never gets the resubscription send operations unless you add them.
- **Credential handling:** Your TalkBox Basic auth username and password are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'send a resubscription SMS' or 'find a contact', and Jentic returns the matching TalkBox operation with its input schema so the agent calls the right endpoint without crawling the full endpoint list.

## Related APIs

- **Mailchimp** — Larger email and marketing automation platform with broader audience and campaign tooling
- **Constant Contact** — Email marketing and contact management aimed at small and mid-size businesses
- **Klaviyo** — Use Klaviyo for behavioural e-commerce flows alongside TalkBox loyalty and voucher actions

## FAQ

### What authentication does the TalkBox API use?

The TalkBox API uses HTTP Basic authentication. You pass a username and API password issued from your TalkBox account on every request. Through Jentic, the credentials are stored in the encrypted vault and the agent receives a scoped token, so the raw API password never enters the agent context.

### Can I issue marketing vouchers with the TalkBox API?

Yes. Use the promotions, offers, and vouchers endpoints to create a promotion, attach an offer, and issue or revoke vouchers for a contact list. The API also lets you tag contacts so vouchers can target specific segments.

### What are the rate limits for the TalkBox API?

The published OpenAPI spec does not declare hard rate limits. TalkBox enforces fair-use limits per account, so batch resubscription and bulk tag operations should be paced and the response status code checked for 429 before retrying.

### How do I send a resubscription SMS to a lapsed contact through Jentic?

Search Jentic for 'send resubscription sms' to find the operation backed by POST `/contact/{id}/send_resubscription_sms.` Load the schema, pass the contact id, and execute. Jentic injects credentials at runtime so your agent never handles the API password.

### Can the TalkBox API create or update contacts in one call?

Yes. The POST `/contact/create_or_update` endpoint upserts a contact based on a match key such as email, applies any new field values, and returns the resulting contact id, which is the cleanest pattern for CRM sync flows.

### How do I find a contact by email without listing every record?

Use GET `/contact/find_first` with a query parameter on email. It returns the first matching contact id, which you can then pass to the contact, tag, or resubscription endpoints to drive the next action.

### Can I limit what my agent is allowed to do with the TalkBox API?

Yes. Because you run your own self-hosted Jentic One instance, your rules decide which TalkBox operations and credentials the agent may use. You can grant a lookup-only agent just GET `/contact/find_first` and the tag endpoints while withholding POST `/contact/{id}/send_resubscription_email` and `/contact/{id}/send_resubscription_sms`, so it can never send messages unless you add those operations. Since TalkBox puts the contact id in the URL path, a rule can also pin the agent to a single contact.