PushizoDocs
Messaging & campaigns

Custom AI agents

Agents that follow your own instructions, review segments and campaign results with the tools you allow and prepare drafts for your approval. They run on a schedule (cron) or manually…

Agents that follow your own instructions, review segments and campaign results with the tools you allow and prepare drafts for your approval. They run on a schedule (cron) or manually. Available on Growth and above while the AI assistant is enabled for the organization (ADR-0089).

Safety boundary

  • The agent has no send, schedule, publish or approve tool. If the model asks for a tool outside the catalog (for example send_campaign) no call is made and the run log shows unknown_tool; a catalog tool that is not allowed shows not_allowed.
  • Write tools only create drafts. A person applies the draft in the dashboard: a segment draft becomes a segment, a campaign draft becomes a campaign in draft status. The draft campaign goes through the usual pre-send check and approval flow.
  • Read tools return aggregated numbers only (no contact ids, emails or phone numbers). Tool arguments and results are not stored.
  • Draft text and the summary pass the banned phrase check.

Tools

ToolTypeDescription
list_segmentsreadSegment names and estimated sizes (at most 25).
campaign_performancereadSent, delivered, opened, clicked and converted counts of campaigns run in the last 7/30/90 days.
delivery_summaryreadDelivery counts by channel and status in the last 1–30 days.
create_segment_draftdraftA segment proposal from a fixed rule list: clicked_7d, not_opened_7d, inactive_30d, event_7d.
create_campaign_draftdraftPush campaign copy (title ≤ 65, body ≤ 240); the audience is existing segments or a segment draft of the same run.

At most 5 drafts are written per run.

Setup

Dashboard → Campaigns → Custom AI agents → Create an agent.

FieldDescription
InstructionsTask and limits (up to 4,000 characters).
Allowed toolsA selection from the catalog above.
Schedule5-field cron and time zone (app time zone when empty); at most hourly. Without it the agent runs manually only.
LimitsSteps per run (default 6, at most 10) and a monthly token cap (default 200,000).

Scheduled runs only happen while the agent is enabled; Run now also works on a disabled agent.

Runs and log

Every 5 minutes the worker scheduler claims due agents and adds them to the custom-agent queue; because the AI provider lives in the API process, the job is processed by the API consumer. No new run starts while the same agent has a pending or running run. Run statuses: pending, running, succeeded, failed, skipped (AI disabled, quota or credits used up, plan feature missing or monthly token cap reached).

API

curl -X POST "https://api.pushizo.com/v1/apps/$APP_ID/custom-agents" \
  -H "Authorization: Bearer $PUSHIZO_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"Weekly analyst","enabled":true,"instructions":"Review last week campaigns and prepare a win-back campaign draft.","tools":["list_segments","campaign_performance","create_segment_draft","create_campaign_draft"],"schedule":{"cron":"0 9 * * 1","timezone":"Europe/Istanbul"}}'

Read endpoints (GET .../custom-agents, .../runs, .../drafts) need the analytics:read scope; writes and POST .../{id}/run need admin. Applying and dismissing drafts happens in a dashboard session only. Node SDK: hs.customAgents.

On this page