> For the complete documentation index, see [llms.txt](https://dev.apirtc.com/apirtc-developer-portal/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://dev.apirtc.com/apirtc-developer-portal/rest-apis-and-integration/apizee-api-rest-description/session-events-api.md).

# Session Events API

## Introduction

Apizee sessions can include interactions such as OCR scans, chat messages, media captures, or survey completions. Until now, this data was not accessible externally.

With the new **Session Events API**, all meaningful in-session actions are exposed via:

* a REST API attached to each ticket
* a webhook that triggers on each new event

These capabilities enable IT systems to:

* Monitor what happens during video sessions
* Automate processes based on session content
* Archive or analyze interaction data

## Authentication and Permissions

Access to these endpoints requires:

* A valid Bearer token
* Proper role permissions to access ticket data

See [Introduction](/apirtc-developer-portal/rest-apis-and-integration/introduction.md#authentication) for a step by step documentation.

> Rate limiting applies to all event endpoints. See [Rate Limits](/apirtc-developer-portal/rest-apis-and-integration/rate-limits.md) for more details.

## Event Model

Each event in the ticket timeline follows a common structure plus event-specific attributes.

### Event-specific payload attributes

Depending on the event type triggered, the webhook payload will contain specific attributes:

<table><thead><tr><th>Event type</th><th>Props value example</th></tr></thead><tbody><tr><td>consent.accepted</td><td></td></tr><tr><td>ticket.sessionStarted</td><td></td></tr><tr><td>geo.ansAllowed</td><td><pre><code> "geoloc":{
  "lat": 48.650032799999998,
  "lng": -3.3655395000000001
 }
</code></pre></td></tr><tr><td>geo.ansDisallowed</td><td></td></tr><tr><td>ticket.approved</td><td><pre><code>"agent": {
    "email": "john.doe@apizee.com",
    "phone": "+3316565454",
    "firstname": "John",
    "lastname": "Doe"
},
</code></pre></td></tr><tr><td>ticket.new</td><td><pre><code>"agent": {
    "email": "john.doe@apizee.com",
    "phone": "+3316565454",
    "firstname": "John",
    "lastname": "Doe"
},
</code></pre></td></tr><tr><td>ticket.assigned</td><td><pre><code>"agent": {
    "email": "john.doe@apizee.com",
    "phone": "+3316565454",
    "firstname": "John",
    "lastname": "Doe"
},
</code></pre></td></tr><tr><td>ticket.completed</td><td><pre><code>"agent": {
    "email": "john.doe@apizee.com",
    "phone": "+3316565454",
    "firstname": "John",
    "lastname": "Doe"
},
</code></pre></td></tr><tr><td>ticket.cancelled</td><td><pre><code>"agent": {
    "email": "john.doe@apizee.com",
    "phone": "+3316565454",
    "firstname": "John",
    "lastname": "Doe"
},
</code></pre></td></tr><tr><td>ticket.closed</td><td><pre><code>"agent": {
    "email": "john.doe@apizee.com",
    "phone": "+3316565454",
    "firstname": "John",
    "lastname": "Doe"
},
</code></pre></td></tr><tr><td>mediaDevice.allowed</td><td><pre><code>"requestor": {
    "email": "jane.doe@issues.llc",
    "phone": "0605040302",
    "firstname": "Jane",
    "lastname": "Doe"
  },
</code></pre></td></tr><tr><td>mediaDevice.disallowed</td><td><pre><code>"requestor": {
    "email": "jane.doe@issues.llc",
    "phone": "0605040302",
    "firstname": "Jane",
    "lastname": "Doe"
  },
</code></pre></td></tr><tr><td>mediaDevice.cameraAllowed</td><td><pre><code>"requestor": {
    "email": "jane.doe@issues.llc",
    "phone": "0605040302",
    "firstname": "Jane",
    "lastname": "Doe"
  },
</code></pre></td></tr><tr><td>mediaDevice.cameraDisallowed</td><td><pre><code>"requestor": {
    "email": "jane.doe@issues.llc",
    "phone": "0605040302",
    "firstname": "Jane",
    "lastname": "Doe"
  },
</code></pre></td></tr><tr><td>mediaDevice.micAllowed</td><td><pre><code>"requestor": {
    "email": "jane.doe@issues.llc",
    "phone": "0605040302",
    "firstname": "Jane",
    "lastname": "Doe"
  },
</code></pre></td></tr><tr><td>mediaDevice.micDisallowed</td><td><pre><code>"requestor": {
    "email": "jane.doe@issues.llc",
    "phone": "0605040302",
    "firstname": "Jane",
    "lastname": "Doe"
  },
</code></pre></td></tr><tr><td>session.established</td><td><pre><code>"requestor": {
    "email": "jane.doe@issues.llc",
    "phone": "0605040302",
    "firstname": "Jane",
    "lastname": "Doe"
  },
</code></pre></td></tr><tr><td>ticket.priorityChanged</td><td><pre><code>"agent": {
    "email": "francois.legoff.ext@apizee.com",
    "phone": "",
    "firstname": "François",
    "lastname": "Le Goff"
 },
"oldPriority": 1,
"newPriority": 0
</code></pre></td></tr><tr><td>ticket.invitationSent</td><td><pre><code>"requestor": {
    "email": "jane.doe@issues.llc",
    "phone": "0605040302",
    "firstname": "Jane",
    "lastname": "Doe"
  },
</code></pre></td></tr><tr><td>ticket.invitationResent</td><td><pre><code>"requestor": {
    "email": "jane.doe@issues.llc",
    "phone": "0605040302",
    "firstname": "Jane",
    "lastname": "Doe"
  },
</code></pre></td></tr><tr><td>ticket.invitationAccepted</td><td><pre><code>"requestor": {
    "email": "jane.doe@issues.llc",
    "phone": "0605040302",
    "firstname": "Jane",
    "lastname": "Doe"
  },
</code></pre></td></tr><tr><td>ticket.invitationDeclined</td><td><pre><code>"requestor": {
    "email": "jane.doe@issues.llc",
    "phone": "0605040302",
    "firstname": "Jane",
    "lastname": "Doe"
  },
</code></pre></td></tr><tr><td><del>ticket.invitationExpired</del></td><td></td></tr><tr><td>ticket.invitationClicked</td><td><pre><code>"requestor": {
    "email": "jane.doe@issues.llc",
    "phone": "0605040302",
    "firstname": "Jane",
    "lastname": "Doe"
  },
</code></pre></td></tr><tr><td>ticket.invitationNotclicked</td><td><pre><code>"requestor": {
    "email": "jane.doe@issues.llc",
    "phone": "0605040302",
    "firstname": "Jane",
    "lastname": "Doe"
  },
</code></pre></td></tr><tr><td>session.agentContacted</td><td><pre><code>"agent": {
    "email": "john.doe@apizee.com",
    "phone": "+3316565454",
    "firstname": "John",
    "lastname": "Doe"
},
</code></pre></td></tr><tr><td>media.pictureTaken</td><td><pre><code>“mediaId”: 342432
</code></pre></td></tr><tr><td>media.pictureSent</td><td><pre><code>“mediaId”: 342432
</code></pre></td></tr><tr><td>survey.answered</td><td><pre><code>"requestor": {
    "email": "contact@flegoff.fr",
    "phone": "",
    "firstname": "",
    "lastname": "contact Flegoff"
 },
"surveyAnswer": {
  "questions" : [
    {"id":12, //SurveyQuestionAnswer id
    "label": {"fr":"Première question ?","en":"Question one?"}, 
    "answer": "Not satisfied" //Not satisfied, Satisfied, Very satisfied
     }, 
    {"id":14, 
    "label": {"fr":"Deuxième question ?","en":"Question two?"}, 
    "answer": "Satisfied" //Not satisfied, Satisfied, Very satisfied
     }
   ], 
   "feedback": "Ceci est un feedback"  
}
</code></pre></td></tr><tr><td>session.agentLeft</td><td><pre><code>"agent": {
    "email": "john.doe@apizee.com",
    "phone": "+3316565454",
    "firstname": "John",
    "lastname": "Doe"
},
</code></pre></td></tr><tr><td>session.userLeft</td><td><pre><code>"requestor": {
    "email": "jane.doe@issues.llc",
    "phone": "0605040302",
    "firstname": "Jane",
    "lastname": "Doe"
  },
</code></pre></td></tr><tr><td>media.OCRDone</td><td><pre><code>"text": "Lorem\nipsum"
</code></pre></td></tr></tbody></table>

## HTTP REST API to access to ticket's events

## GET /api/v3/tickets/{ticketId}/events

> Get an event list for a ticket.

```json
{"openapi":"3.0.0","info":{"title":"Apizee Cloud API documentation","version":"3.0"},"tags":[{"name":"tickets","description":"API to manage tickets"}],"servers":[{"url":"https://cloud.apizee.com/","description":"Default server"}],"security":[{"access_token":[]}],"components":{"securitySchemes":{"access_token":{"type":"http","description":"Please fill in the field with the token obtained after authentication using the /token method","scheme":"bearer"}}},"paths":{"/api/v3/tickets/{ticketId}/events":{"get":{"tags":["tickets"],"summary":"Get an event list for a ticket.","operationId":"api.v3.tickets.events","parameters":[{"name":"ticketId","in":"path","description":"ID of the wanted ticket","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Good case","content":{"application/json":{"schema":{}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{}}}},"404":{"description":"Not found case","content":{"application/json":{"schema":{}}}}}}}}}
```

## Listen to webhook callbacks

The `conversationevent.create` webhook notifies your system in real time whenever a new event occurs during a video session linked to a support ticket. It enables your backend to react immediately to user interactions such as media capture, OCR scans, or survey responses.

#### How It Works

Once configured, the webhook is triggered for each new event in a ticket's timeline. Your endpoint receives a `POST` request with a JSON payload describing the event.

#### Example Payload

```json
{
  "event": "create",
  "time": 1749581447,
  "object": "conversationevent",
  "objectId": 1266,
  "props": {
    "eventType": "media.OCRDone",  // <-- common payload attribute
    "eventCode": 41,  // <-- common payload attribute
    "conversationId": 548,  // <-- common payload attribute
    "ticketId": 361,  // <-- common payload attribute
    "text": "text captured by OCR" // <-- event-specific attribute
    }
}
```

#### Payload Fields

{% hint style="info" %}
To get a complete list of the webhooks payload attributes and how to configure webhooks, please refer to [Webhooks](/apirtc-developer-portal/rest-apis-and-integration/webhooks.md).
{% endhint %}