Campaigns, automations and agents

Campaigns, automations, AI agents and scheduled messages follow the same rules as the app: whatever the API refuses, the app would refuse too.

Bulk template campaign

1. Pick the number (GET https://api.converzap.com/v1/channels) and an approved template (GET https://api.converzap.com/v1/templates?status=approved).
2. Create the draft — nothing is sent yet:

curl -X POST https://api.converzap.com/v1/campaigns \
  -H "Authorization: Bearer czk_live_YOUR_KEY" \
  -H "Idempotency-Key: black-friday-campaign-1" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Black Friday",
    "channel": "123456789012345",
    "template_id": "TEMPLATE_UUID",
    "variables": { "body:1": { "kind": "field", "field": "first_name", "fallback": "customer" } },
    "audience": { "labels": ["customer"], "exclude_labels": ["inactive"] },
    "rate_per_minute": 60
  }'

1. Start it: POST https://api.converzap.com/v1/campaigns/{id}/start. With a future scheduled_at it becomes scheduled; otherwise it goes to sending.
2. Track it with GET https://api.converzap.com/v1/campaigns/{id} (stats: sent, delivered, read, failed, skipped) and control it with pause, resume and cancel.

Variables: each template variable (body:1, body:name, header:1, button:0) gets a contact field (first_name, name, company, city, uf, email, phone — plus, from the contact's company data found by enrichment, razao_social, cnpj, endereco_empresa and socios, up to 3), a custom field ({"kind": "custom", "key": "plan"}) or fixed text ({"kind": "text", "value": "BF10"}). A contact with no value and no fallback is skipped (instead of a Meta error).

Audience: all, list_ids, labels, segment_ids and the exclusions exclude_labels / exclude_segment_ids. Opted-out contacts, landlines and contacts without a phone are never included.

Common errors: 402 limit_reached (the plan's monthly contact limit or a number outside the plan), 409 conflict (action not valid in the current state, e.g. starting a campaign that already started), 400 invalid_request with errors[] listing what is missing to start.

Automations (journeys)

Automations are built in the app; through the API you list them and enroll contacts:

curl -X POST https://api.converzap.com/v1/automations/{id}/enrollments \
  -H "Authorization: Bearer czk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contact_id": "CONTACT_UUID" }'

• The automation must be active (otherwise 409).
• Each contact goes through an automation once: enrolling again returns 409.
• DELETE https://api.converzap.com/v1/automations/{id}/enrollments/{contact_id} stops the journey (stopped).
• Tip: to start a journey from your system, create the automation with a manual trigger and enroll through the API.

AI agents

• GET https://api.converzap.com/v1/agents lists the agents (status draft, active, paused).
• POST https://api.converzap.com/v1/agents/{id}/activate turns the agent on; with {"channel": "<phone_number_id>"} it goes live on that number. The activation checklist, the active agent limit and "one agent per number" apply as in the app.
• POST https://api.converzap.com/v1/agents/{id}/pause stops replies.
• To take over or hand back ONE conversation, use POST https://api.converzap.com/v1/conversations/{id}/ai-agent.

Scheduled messages

POST https://api.converzap.com/v1/conversations/{id}/scheduled-messages with send_at (1 minute to 30 days ahead) and text or template (id or name + language, with params as when sending). Text only if the 24-hour window is still open at the chosen time (otherwise 409 outside_24h_window). With cancel_if_replied (default) the message is not sent if the contact writes first. Cancel: DELETE https://api.converzap.com/v1/scheduled-messages/{id}.

Postman and Insomnia

1. In Postman: Import → Link and paste https://api.converzap.com/v1/openapi.json?lang=en.
2. In the new collection, Authorization → Bearer Token with your key (ideally in an environment variable, never in code).
3. The baseUrl already comes as https://api.converzap.com/v1.

In Insomnia: Create → Import → From URL with the same address. Re-import when the changelog announces a new version.