REST-API-Endpunkte für Kampagnen

Mit Kampagnen führen Sie ausgehende Massenwahl zu einer Kontaktliste mit einem konfigurierten KI-Assistenten durch. Sie legen eine Kampagne mit Zeitplan und Wahloptionen an, fügen Kontakte hinzu und starten sie — die API deckt Erstellung, Kontaktlisten und Ausführung ab.

List campaigns

GET /api/crm/campaigns Returns a paginated list of campaigns for a team. You can filter by status, assistant, and whether to include soft-deleted campaigns.

Query parameters

teamId

string

erforderlich

The team ID to list campaigns for.

status

string

Filter campaigns by status. One of: draft, scheduled, running, paused, completed, cancelled.

assistantId

string

Filter campaigns assigned to a specific assistant ID.

deleted

string

Controls whether to include soft-deleted campaigns. One of: exclude (default), include, only.

limit

integer

Maximum number of records to return. Defaults to 50.

offset

integer

Number of records to skip for pagination. Defaults to 0.

Example request

curl "https://<your-domain>/api/crm/campaigns?teamId=team_01j...&status=running&limit=20" \
  -H "Authorization: Bearer <token>"

Antwort

{
  "success": true,
  "campaigns": [
    {
      "id": "camp_01j...",
      "team_id": "team_01j...",
      "assistant_id": "asst_01j...",
      "company_id": "comp_01j...",
      "name": "Q1 Outreach",
      "description": "Qualify leads from the January trade show",
      "from_number": "+12025551234",
      "status": "running",
      "call_window_start": "09:00",
      "call_window_end": "17:00",
      "call_window_timezone": "America/New_York",
      "max_concurrent_calls": 5,
      "total_contacts": 200,
      "contacts_called": 80,
      "contacts_completed": 65,
      "contacts_answered": 55,
      "created_at": "2024-01-10T09:00:00Z",
      "updated_at": "2024-01-15T14:30:00Z"
    }
  ],
  "count": 1,
  "limit": 20,
  "offset": 0
}

campaigns

array

Array of campaign objects.

campaigns[].id

string

Unique campaign identifier.

campaigns[].team_id

string

The team this campaign belongs to.

campaigns[].assistant_id

string

The assistant assigned to place calls in this campaign.

campaigns[].company_id

string

The company associated with this campaign.

campaigns[].name

string

Campaign name.

campaigns[].status

string

Current campaign status: draft, scheduled, running, paused, completed, or cancelled.

campaigns[].from_number

string

The phone number used as the caller ID for outbound calls.

campaigns[].call_window_start

string

Start of the daily call window in HH:MM format.

campaigns[].call_window_end

string

End of the daily call window in HH:MM format.

campaigns[].call_window_timezone

string

IANA timezone for the call window (for example, America/New_York).

campaigns[].max_concurrent_calls

integer

Maximum number of calls placed simultaneously.

campaigns[].total_contacts

integer

Total number of contacts in the campaign.

campaigns[].contacts_called

integer

Number of contacts where a call attempt was made.

campaigns[].contacts_completed

integer

Number of contacts where the call reached a terminal state.

campaigns[].contacts_answered

integer

Number of contacts who answered the call.

count

integer

Total number of campaigns matching the filters (before pagination).

limit

integer

The limit value applied to this response.

offset

integer

The offset value applied to this response.

Create a campaign

POST /api/crm/campaigns Creates a new outbound calling campaign. The campaign starts in draft status. Add contacts and then call the run endpoint to begin dialing.

Request body

teamId

string

erforderlich

The team ID that owns this campaign.

assistantId

string

erforderlich

The ID of the assistant that will place calls.

companyId

string

erforderlich

The company ID to associate with this campaign.

fromNumberIds

array

erforderlich

An array of phone number IDs to use as caller IDs. Talkturo rotates across these numbers when placing calls.

name

string

erforderlich

A human-readable name for the campaign.

description

string

Optional description of the campaign’s purpose.

scheduledStartAt

string

ISO 8601 datetime for when the campaign should start automatically. If omitted, you start the campaign manually via the run endpoint.

callWindowStart

string

Start of the daily calling window in HH:MM format (for example, "09:00"). Calls only go out during this window.

callWindowEnd

string

End of the daily calling window in HH:MM format (for example, "17:00").

callWindowTimezone

string

IANA timezone for the call window (for example, "America/New_York").

maxConcurrentCalls

integer

Maximum number of simultaneous outbound calls. Defaults to 3.

maxAttemptsPerContact

integer

How many times to retry a contact who does not answer. Defaults to 3.

retryDelayMinutes

integer

Minutes to wait before retrying a contact. Defaults to 60.

settings

object

Additional campaign settings as a freeform object.

Example request

curl -X POST https://<your-domain>/api/crm/campaigns \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "teamId": "team_01j...",
    "assistantId": "asst_01j...",
    "companyId": "comp_01j...",
    "fromNumberIds": ["pn_01j..."],
    "name": "Q1 Trade Show Follow-Up",
    "description": "Follow up with leads from the January trade show",
    "callWindowStart": "09:00",
    "callWindowEnd": "17:00",
    "callWindowTimezone": "America/New_York",
    "maxConcurrentCalls": 5,
    "maxAttemptsPerContact": 3,
    "retryDelayMinutes": 60
  }'

Antwort

{
  "success": true,
  "campaign": {
    "id": "camp_01j...",
    "team_id": "team_01j...",
    "assistant_id": "asst_01j...",
    "company_id": "comp_01j...",
    "name": "Q1 Trade Show Follow-Up",
    "status": "draft",
    "call_window_start": "09:00",
    "call_window_end": "17:00",
    "call_window_timezone": "America/New_York",
    "max_concurrent_calls": 5,
    "total_contacts": 0,
    "contacts_called": 0,
    "contacts_completed": 0,
    "contacts_answered": 0,
    "created_at": "2024-01-15T10:00:00Z",
    "updated_at": "2024-01-15T10:00:00Z"
  }
}

Add contacts to a campaign

POST /api/crm/campaigns/{id}/contacts Adds one or more existing contacts to a campaign. Contacts must already exist in your CRM. Use the contacts endpoints to create them first if needed.

Path parameters

string

erforderlich

The campaign ID to add contacts to.

Request body

contactIds

array

erforderlich

An array of contact ID strings to add to the campaign.

Example request

curl -X POST https://<your-domain>/api/crm/campaigns/camp_01j.../contacts \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "contactIds": ["cont_01j...", "cont_02k...", "cont_03l..."]
  }'

Antwort

{
  "success": true
}

Start a campaign

POST /api/crm/campaigns/{id}/run Initiates outbound calls for a campaign. Talkturo dials all contacts in pending or queued status, up to the campaign’s maxConcurrentCalls limit. Use dryRun: true to preview which calls would be placed without actually dialing.

Path parameters

string

erforderlich

The campaign ID to start.

Request body

accountSlug

string

Your account slug.

maxCalls

integer

Cap the number of calls started in this execution. Useful for gradual rollouts.

dryRun

boolean

When true, the API returns which calls would be started without actually placing them. Use this to verify campaign configuration before going live.

Example request

curl -X POST https://<your-domain>/api/crm/campaigns/camp_01j.../run \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "accountSlug": "my-team",
    "maxCalls": 20
  }'

Antwort

{
  "success": true,
  "started": 18,
  "failed": 2,
  "calls": [...],
  "errors": [
    "Contact cont_09x... has no phone number",
    "Contact cont_10y... is marked do-not-call"
  ],
  "message": "Started 18 calls",
  "dryRun": false
}

started

integer

Anzahl der erfolgreich initiierten Anrufe.

failed

integer

Anzahl der Kontakte, die in diesem Lauf nicht angerufen werden konnten.

calls

array

Array von Anrufobjekten für die gestarteten Anrufe.

errors

array

Array von Fehlermeldungszeichenfolgen, die beschreiben, warum einzelne Kontakte übersprungen wurden.

message

string

Für Menschen lesbare Zusammenfassung des Laufs.

dryRun

boolean

Spiegelt den „dryRun“-Wert Ihrer Anfrage wider.

Lebenszyklus des Kampagnenstatus

Status	Beschreibung
„Entwurf“	Kampagne erstellt, aber noch nicht gestartet
„geplant“	Die Kampagne soll zu einem späteren Zeitpunkt „scheduledStartAt“ starten
„laufen“	Es werden aktiv Anrufe getätigt
`pausiert`	Kampagne vorübergehend gestoppt; kann wieder aufgenommen werden
„abgeschlossen“	Alle Kontakte sind erreicht oder erschöpft
„abgesagt“	Kampagne dauerhaft gestoppt

Überblick

Endpunkte

Webhooks

REST-API-Endpunkte für Kampagnen

List campaigns

Query parameters

Example request

Antwort

Create a campaign

Request body

Example request

Antwort

Add contacts to a campaign

Path parameters

Request body

Example request

Antwort

Start a campaign

Path parameters

Request body

Example request

Antwort

Lebenszyklus des Kampagnenstatus

Überblick

Endpunkte

Webhooks

Documentation Index

​List campaigns

​Query parameters

​Example request

​Antwort

​Create a campaign

​Request body

​Example request

​Antwort

​Add contacts to a campaign

​Path parameters

​Request body

​Example request

​Antwort

​Start a campaign

​Path parameters

​Request body

​Example request

​Antwort

​Lebenszyklus des Kampagnenstatus

List campaigns

Query parameters

Example request

Antwort

Create a campaign

Request body

Example request

Antwort

Add contacts to a campaign

Path parameters

Request body

Example request

Antwort

Start a campaign

Path parameters

Request body

Example request

Antwort

Lebenszyklus des Kampagnenstatus