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

string

erforderlich

The team ID to list campaigns for.

string

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

string

Filter campaigns assigned to a specific assistant ID.

string

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

integer

Maximum number of records to return. Defaults to 50.

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
}

array

Array of campaign objects.

string

Unique campaign identifier.

string

The team this campaign belongs to.

string

The assistant assigned to place calls in this campaign.

string

The company associated with this campaign.

string

Campaign name.

string

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

string

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

string

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

string

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

string

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

integer

Maximum number of calls placed simultaneously.

integer

Total number of contacts in the campaign.

integer

Number of contacts where a call attempt was made.

integer

Number of contacts where the call reached a terminal state.

integer

Number of contacts who answered the call.

integer

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

integer

The limit value applied to this response.

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

string

erforderlich

The team ID that owns this campaign.

string

erforderlich

The ID of the assistant that will place calls.

string

erforderlich

The company ID to associate with this campaign.

array

erforderlich

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

string

erforderlich

A human-readable name for the campaign.

string

Optional description of the campaign’s purpose.

string

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

string

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

string

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

string

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

integer

Maximum number of simultaneous outbound calls. Defaults to 3.

integer

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

integer

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

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

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

string

Your account slug.

integer

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

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
}

integer

Anzahl der erfolgreich initiierten Anrufe.

integer

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

array

Array von Anrufobjekten für die gestarteten Anrufe.

array

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

string

Für Menschen lesbare Zusammenfassung des Laufs.

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

​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