Record integration activity

Record actions from your integration as Timeline Events so operators can see what happened in Stora. This guide records an outbound call against a contact.

Before you start

You need:

An access token with public.timeline_event:write. You do not need source or template read scopes to create events with known IDs.
The source and template IDs for your integration. Follow the setup below for either a partner app or a custom operator integration.

For the outbound-call example in this guide, you also need the ID of a contact in the connected operator’s account. Other event types use the references required by their template. To run this guide’s curl examples, set STORA_ACCESS_TOKEN in your shell to your access token. STORA_ACCESS_TOKEN is an example variable name, not an API requirement.

Choose your integration’s setup

A Timeline Source identifies your integration on the operator’s timeline. A Timeline Template defines the event’s message and variables. Source setup differs between partner apps and custom integrations built for one operator.

Partner app
Operator integration

Ask Stora to create a global source for your integration before you release it. Stora provides a source ID that you can hardcode in your integration. The source is available to all operators, so use the same ID across all operator connections. You do not need to create or discover a source for each operator.Agree with Stora on the templates that fit the actions your integration records. If no existing template fits your use case, request one in advance.Hardcode the agreed template IDs in your integration. Map each supported action to its intended template. Do not accept arbitrary source or template IDs from operators or incoming requests, and do not discover templates at runtime.

Do not include template-related scopes in your partner application’s requested scopes, including public.timeline_template:read. Use hardcoded template IDs to limit the integration to its intended events and prevent template misuse.

For an operator’s own integration, create a custom source in that operator’s Backoffice. You do not need Stora to provision a global source.

In Settings, open Developers, then Timeline events.
Under Sources, click Edit.
Click Add Source.
Enter the integration’s Name. Optionally add an Icon and Website URL.
Click Create Source.

The custom source is available only to the operator where you created it. Save its ID in that operator’s integration configuration. Do not reuse the ID for another operator.To retrieve the source ID during setup, use List all Sources with a credential that has public.timeline_source:read.For templates, return to Timeline events and click View under Templates to browse the shared template library. Creating a custom source does not create an operator-specific template. If no template fits your use case, ask Stora for one.To retrieve a template ID during setup, use List all Templates with public.timeline_template:read. Save the chosen ID in the integration’s configuration. Source and template read scopes are not required for event creation once you have the IDs.

Prepare the example’s event data

For the Outbound call template used below, provide the contact reference. You can also supply a duration string in variables. Other templates can require references such as a unit, subscription, or invoice. Check the references and variables for your chosen template. For a partner app, confirm these requirements with Stora during setup. Creating an event with a missing required reference fails. Custom variables can be incomplete on creation, but omitted values can leave the rendered message incomplete. Supply the values needed to describe the action.

Create the event

Generate an idempotency key once for this action:

EVENT_KEY="$(uuidgen)"

Replace tsrc_REPLACE with the source ID for your integration’s setup and aetpl_REPLACE with the Outbound call template ID. For a partner app, use the hardcoded IDs agreed with Stora. For a custom operator integration, use the IDs saved in its configuration. Replace con_REPLACE with the contact ID for this example and the external record details with your own record ID and URL.

curl --request POST \
	'https://public-api.stora.co/2025-09/timeline/events' \
	--header "Authorization: Bearer $STORA_ACCESS_TOKEN" \
	--header 'Content-Type: application/json' \
	--header "Idempotency-Key: $EVENT_KEY" \
	--data '{
		"source": {"id": "tsrc_REPLACE"},
		"template": {"id": "aetpl_REPLACE"},
		"contact": {"id": "con_REPLACE"},
		"description": "Discussed the requested move-in date.",
		"variables": {"duration": "2 minutes"},
		"external": {
			"id": "call_123",
			"url": "https://example.com/calls/call_123"
		}
	}'

A successful request returns 201 with an event object. Save event.id beside your originating record. Open the contact in Stora Backoffice and confirm that the call appears on its timeline with your source and external link. description adds a note alongside the template message. It does not replace the message. external.id identifies the record in your system, and external.url links to that record.

Handle retries and corrections

If the create request times out, retry with the same body and EVENT_KEY. Do not generate a new key for a retry. Use a different key for a different action. An external record ID is not a substitute for an idempotency key. If you need to correct an event, use its saved ID with Update an Event. Updates validate required custom variables too, so preserve the values needed by the template. Only update or delete events that your integration is responsible for. For failed requests, inspect the error response before retrying.

Getting started

Developer Portal

Manage accounts

Concepts

Working with the API

Building integrations

Marketplace

Resources

Record integration activity

Before you start

Choose your integration’s setup

Prepare the example’s event data

Create the event

Handle retries and corrections

​Before you start

​Choose your integration’s setup

​Prepare the example’s event data

​Create the event

​Handle retries and corrections

Before you start

Choose your integration’s setup

Prepare the example’s event data

Create the event

Handle retries and corrections