Contact Events

Contact events are timestamped actions your app records about a user. They appear in the contact’s timeline and give your support team instant context: “This customer upgraded their plan two days ago and now they’re asking about billing” tells a very different story than a cold support ticket.

What an event looks like

Each event has:

• Name: a short label like plan_upgraded, trial_started, shop_installed.
• Occurred at: the exact time the action happened.
• Properties (optional): any additional key-value data relevant to the event.

Sending events via the API

Events are sent from your server (not the widget). Use the Convot API:

POST /api/v1/contacts/:contact_id/events
Authorization: Bearer YOUR_API_KEY

{
  "name": "plan_upgraded",
  "occurred_at": "2026-06-07T10:30:00Z",
  "properties": {
    "from_plan": "starter",
    "to_plan": "pro",
    "mrr_delta": 50
  }
}

The contact_id is the Convot contact’s integer ID, visible in the contact profile URL or returned by the contacts API.

Viewing events

Events appear in the Contact Events section of the contact’s profile page. They’re listed in reverse chronological order.

During a conversation, the contact sidebar shows recent events in the timeline section so agents have context without leaving the inbox.

Event naming conventions

Use consistent, lowercase, underscore-separated event names. A few suggestions for Shopify app developers:

• shop_installed
• shop_uninstalled
• plan_upgraded
• plan_downgraded
• trial_started
• trial_ended
• feature_enabled
• charge_failed

Consistent names make it easier to search and filter in the future.

Events vs. custom data

Use custom data for the current state of a contact (e.g., plan: "pro", order_count: 42). Use contact events for things that happened at a specific point in time (e.g., “upgraded from Starter to Pro on June 7th”).

Both are visible in the contact sidebar and profile.