# 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://dev.apirtc.com/apirtc-developer-portal/rest-apis-and-integration/apizee-api-rest-description/session-events-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.