Tickiti

Tickiti Interventions – Technical Reference

This article and the rest of the API documentation in this section are written for a technical audience — integrators and developers connecting external systems to Tickiti. Familiarity with HTTP, REST, JSON and bearer-token authentication is assumed.

This section provides the precise technical contract required to integrate a remote system with Tickiti interventions. For the conceptual explanation see Tickiti intervention integrator’s guide; for the fast path see Interventions quick start.

1. Terminology

TermMeaning
InterventionA named workflow definition in Tickiti that maps to a remote decision process.
InterventionPayloadA stored instance of an intervention attached to a ticket.
UIDA unique identifier provided by the remote system representing a specific intervention instance.
Data bagArbitrary structured data supplied by the remote system and edited by staff.
Epilog endpointThe remote system endpoint that Tickiti calls when staff submit the intervention.
Templates{intervention}.private, .public, .final templates used to render ticket responses.

2. Remote → Tickiti API

Endpoint

POST /api/create_ticket

Headers

Authorization: Bearer {tickiti_api_token}
Idempotency-Key: {uuid}
Content-Type: application/json
  1. Token must include ability: create-ticket
  2. Idempotency-Key is required for safe retries.

Request Body Schema

{
"originator_email_address": "string (required)",
"intervention": "string (required)",
"uid": "string (required)",
"data": {
"data": { }
}
}

Field Definitions

FieldTypeRequiredDescription
originator_email_addressstringYesEnd user email address
interventionstringYesMust match Tickiti intervention name
uidstringYesUnique identifier in remote system
data.dataobjectYesStructured key/value data

Example

{
"originator_email_address": "customer@example.com",
"intervention": "discount_request",
"uid": "order-1001-discount",
"data": {
"data": {
"currency": "GBP",
"order_price": 100,
"accept": false
}
}
}

Success Response

{
"ok": true,
"data": {
"used_intervention": true,
"queue": "Inbox"
}
}

3. Tickiti → Remote Epilog Call

When staff submit the ticket response, Tickiti dispatches InterventionTicketEpilogJob.

Endpoint

Configured per intervention:

remote_epilog_url

Headers

Authorization: Bearer {remote_bearer_token}
Content-Type: application/json
Accept: application/json

Request Body Schema

{
"ticket_id": "integer",
"response_id": "integer",
"uid": "string",
"intervention": "string",
"action": "string",
"data": { }
}

Field Definitions

FieldDescription
ticket_idTickiti internal ticket id
response_idID of staff response that triggered this
uidRemote system unique identifier
interventionIntervention name
actionUsually "submit"
dataUpdated intervention data bag

Example

{
"ticket_id": 12345,
"response_id": 67890,
"uid": "order-1001-discount",
"intervention": "discount_request",
"action": "submit",
"data": {
"currency": "GBP",
"order_price": 95,
"accept": true
}
}

4. Remote Epilog Response

Minimum Required

{
"ok": true
}

Optional Finalization Payload

If you want Tickiti to:

  1. Mark the intervention accepted
  2. Append audit text
  3. Post a final ticket response

Return:

{
"ok": true,
"ticket_id": 12345,
"uid": "order-1001-discount",
"intervention": "discount_request",
"final": {
"response_id": 67890,
"ticket_audit": "Discount approved at 95 GBP. Order updated.",
"remote_reference": "ORD-1001"
}
}

Final Object Fields

FieldRequiredDescription
response_idYesMust match triggering response
ticket_auditYesAppended to response audit log
additional fieldsNoAvailable in {intervention}.final template

5. HTTP Requirements

RequirementDescription
Response codeMust return HTTP 200
TimeoutControlled by remote_timeout_seconds (default 10s)
AuthenticationBearer token required
RetriesJob retries on failure (exponential backoff)
IdempotencyRemote must handle duplicate calls safely

6. Intervention Configuration (Tickiti)

Each intervention defines:

Core Fields

FieldPurpose
nameUnique immutable identifier
titleDisplay name
queue_nameTarget queue
notify_inbox_managersNotification flag
fma_inbox_managersEscalation flag

Remote Settings

FieldPurpose
remote_nameUsed for token name
remote_epilog_urlRemote callback endpoint
remote_bearer_tokenStored encrypted
remote_timeout_secondsHTTP timeout
remote_enabledEnable/disable integration

UI Field Types

TypeBehavior
textText input
checkboxBoolean toggle
labelStatic informational text
hrHorizontal divider

Label Token Resolution

Labels may include tokens:

Order price (net) {{currency}}

Tokens resolve from:

data.data.currency

7. Template Requirements

Tickiti looks for templates:

{intervention}.private
{intervention}.public
{intervention}.final

Only .private is required.

8. Error Handling Contract

If the remote:

  1. Returns non-200 → Tickiti retries.
  2. Times out → Tickiti retries.
  3. Throws 4xx/5xx → Job retries until max attempts reached.

Remote systems must:

  1. Handle duplicate epilog calls safely.
  2. Use uid as authoritative reference.

9. Security Model

DirectionAuth model
Remote → TickitiSanctum API token
Tickiti → RemoteConfigured Bearer token
Token storageEncrypted in DB
Tokens never displayedAfter creation

10. Data Storage Model (Tickiti)

Each intervention instance creates:

intervention_payloads
id
ticket_id
name
uid
payload_data (json)
accepted
accepted_at
completed_at

11. Operational Constraints

  1. uid must be globally unique within remote domain.
  2. Intervention name cannot change after creation.
  3. Remote URL must support JSON.
  4. Payload size should remain modest (< 32KB recommended).

12. Recommended Best Practices

✔ Use stable domain IDs for uid

✔ Always return { ok:true } on success

✔ Make epilog idempotent

✔ Include meaningful ticket_audit text

✔ Log failures in remote system