Actions — Pitfalls

Writing a non-writable action type

Symptom. POST /lead/{leadId}/action returns 400 BAD_REQUEST with "Only custom actions and payment actions can be created".

Cause. The public API can only write custom actions and PAYMENT actions. Built-in types like OUTGOING_CALL, INCOMING_WHATSAPP_MSG, and LEAD_ASSIGNMENT are recorded automatically by telecrm in response to real events; they cannot be synthesized through the API.

Fix. If you need to mark a call or message manually, create a custom action representing it and write that instead.

Using the ACTION_ prefix

Symptom. Custom action create returns 400 or the action is silently dropped.

Cause. The Sync API uses the bare numeric code for custom actions ("1001", "1002"). The ACTION_ prefix ("ACTION_1001") is exclusive to the Async API.

Fix. Drop the prefix. The format-comparison table is in Actions → The ACTION_ prefix.

- { "type": "ACTION_1001", "fields": { "note": "..." } }
+ { "type": "1001", "fields": { "note": "..." } }

Trying to change amount or currency on a payment

Symptom. POST /lead/{leadId}/action/{actionId} returns 400 with "Cannot update amount, currency, or paymentid fields for existing payment action.".

Cause. Payment actions are immutable except for status. The amount, currency, and external payment ID are locked in at creation.

Fix. Send only type and status in the update body. If the original payment data was wrong, void it (e.g. set status: CANCELLED) and create a new payment action with the correct values.

Per-action partial success on batch create

Symptom. Some actions in a batch are missing on the lead even though the request returned 200.

Cause. POST /lead/{leadId}/action processes each action independently. Failed entries return action_id: null and status: IGNORED; successful ones return their new IDs alongside.

Fix. Always inspect the per-entry actions[].status and the remarks array. Anything IGNORED did not persist — re-issue after fixing the underlying validation error.

Using search to fetch a built-in action's full body

Symptom. Search returns matching INCOMING_CALL entries but GET /action/{actionId} on each one returns 400 BAD_REQUEST.

Cause. The single-action GET endpoint can only return custom actions and payment actions. Built-in types appear in search results (so you can confirm activity occurred) but their full bodies are not exposed through the API.

Fix. Use search to count or detect, but expect that only type is meaningful for built-in entries. Open the lead in the dashboard for full call/message details.

Forgetting required payment fields on create

Symptom. Payment action returns IGNORED in remarks with a missing-field error.

Cause. A payment action requires type, status, currency, and amount together. Omitting any of them causes the entry to be dropped.

Fix. Always include all four. See Actions → PAYMENT for the full schema.