Skip to content

Voxxrin APIs for Organizers

Jump to bottom
Frédéric Camblor edited this page Nov 11, 2024 · 9 revisions

Voxxrin has a number of HTTP APIs used for organizers.

Pre-requisites

To call these APIs, you will need to know these important variables:

  • baseUrl for the Voxxrin environment you want to target. For instance, for Demo environment one, it will be https://api-demo.voxxr.in

  • secretToken allowing you to call the API. This token will look like: <tokenType>:<event or event family name>:<uuid v4> where tokenType can be valued with eventOrganizer|familyOrganizer|eventRoomStatsContributor|familyRoomStatsContributor|eventStats|familyStats (example: eventOrganizer:my-super-conference:1234567-89ab-cdef-1234567890ab).
    This secretToken should be shared with you by a Voxxrin Administrator.

  • eventId corresponding to the event you want to get/update informations. This is generally a short name and you can guess it by looking at the URL on your Voxxrin instance:

Event_id_in_url
  • spaceToken (for private events only) allowing you to access / interact with your voxxrin private space. This token looks like <space name>_<uuid v4> (example: my-private-space_fedcba9-8765-4321-fedcba987654) and can be guessed by looking at the URL on your Voxxrin instance:
Gathering_private_space_token

API Endpoints

Trigger an event's refresh schedule request (through your event's crawler)

URIs:

  • Any event: POST {{baseUrl}}/api/crawlers/{{crawlerId}}/refreshScheduleRequest?token={{secretToken}}
Details

Params:

  • [path] baseUrl*: see Pre-requisites section
  • [query] secretToken*: see Pre-requisites section
  • [query] crawlerId*: should be a crawler code which should be provided by Voxxrin Administrators

Allowed token types:

  • eventOrganizer: for event organizers
  • familyOrganizer: for event family organizers

Dummy call example:

curl --request POST \
  --url 'https://api-demo.voxxr.in/api/crawlers/myEvt24/refreshScheduleRequest?token=eventOrganizer%3AmyEvt24%3A1234567-89ab-cdef-1234567890ab'
Example payload response 
{
  "eventId": "myEvt24",
  "days": [
    "thursday"
  ],
  "descriptorUrlUsed": "https://path/to/crawler/descriptor.json",
  "durationInSeconds": 1.767000363,
  "messages": []
}

Get event's talks statistics (favorites) for every talks

URIs:

  • Public events: GET {{baseUrl}}/api/events/{{eventId}}/talksStats?token={{secretToken}}
  • Private events: GET {{baseUrl}}/api/spaces/{{spaceToken}}/events/{{eventId}}/talksStats?token={{secretToken}}
Details

Params:

  • [path] baseUrl*, spaceToken*, eventId*: see Pre-requisites section
  • [query] secretToken*: see Pre-requisites section

Important Note: this endpoint is ETag-friendly. It means that:

  • It will return an etag response header when calling it
  • You can pass this etag response header to your next request's X-If-None-Match (*) request header: if nothing has changed, an empty payload with HTTP status 304 Not Modified will be returned.

(*) X-If-None-Match custom header has to be used instead of standard If-None-Match header, because Firebase Hosting (which is used for Voxxrin API endpoints) is currently filtering out If-Not-Match header in firebase cloud functions (more about this on this stackoverflow)

Allowed token types:

  • eventOrganizer: for event organizers
  • familyOrganizer: for event family organizers
  • eventStats: for tools requiring event stats (such as conference walls)
  • familyStats: for family-wide tools requiring event stats (such as conference walls)

Dummy call sample:

curl --request GET \
  --url 'https://api-demo.voxxr.in/api/events/myEvt24/talksStats?token=eventOrganizer%3AmyEvt24%3A1234567-89ab-cdef-1234567890ab'
Example payload response 
{
  "perTalkStats": [
    {
      "talkId": "t001",
      "talkTitle": "A super talk title",
      "speakers": [
        "John Doe"
      ],
      "totalFavoritesCount": 42
    },
    ...
  ]
}

Get event's daily ratings for talks

URIs:

  • Public events: GET {{baseUrl}}/api/events/{{eventId}}/dailyRatings/stats?token={{secretToken}}
  • Private events: GET {{baseUrl}}/api/spaces/{{spaceToken}}/events/{{eventId}}/dailyRatings/stats?token={{secretToken}}
Details

Params:

  • [path] baseUrl*, spaceToken*, eventId*: see Pre-requisites section
  • [query] secretToken*: see Pre-requisites section

Important Note: this endpoint is ETag-friendly. It means that:

  • It will return an etag response header when calling it
  • You can pass this etag response header to your next request's X-If-None-Match (*) request header: if nothing has changed, an empty payload with HTTP status 304 Not Modified will be returned.

(*) X-If-None-Match custom header has to be used instead of standard If-None-Match header, because Firebase Hosting (which is used for Voxxrin API endpoints) is currently filtering out If-Not-Match header in firebase cloud functions (more about this on this stackoverflow)

Allowed token types:

  • eventOrganizer: for event organizers
  • familyOrganizer: for event family organizers

Dummy call sample:

curl --request GET \
  --url 'https://api-demo.voxxr.in/api/events/myEvt24/dailyRatings/stats?token=eventOrganizer%3AmyEvt24%3A1234567-89ab-cdef-1234567890ab'
Example payload response 
{
  "dailyFeedbacks": [
    {
      "dayId": "thursday",
      "totalRatings": 42
    }
  ]
}

Get event's top talks

Reminder: Top talks constraints are customizable at the conference descriptor level

URIs:

  • Public events: GET {{baseUrl}}/api/events/{{eventId}}/topTalks?token={{secretToken}}
  • Private events: GET {{baseUrl}}/api/spaces/{{spaceToken}}/events/{{eventId}}/topTalks?token={{secretToken}}
Details

Params:

  • [path] baseUrl*, spaceToken*, eventId*: see Pre-requisites section
  • [query] secretToken*: see Pre-requisites section

Important Note: this endpoint is ETag-friendly. It means that:

  • It will return an etag response header when calling it
  • You can pass this etag response header to your next request's X-If-None-Match (*) request header: if nothing has changed, an empty payload with HTTP status 304 Not Modified will be returned.

(*) X-If-None-Match custom header has to be used instead of standard If-None-Match header, because Firebase Hosting (which is used for Voxxrin API endpoints) is currently filtering out If-Not-Match header in firebase cloud functions (more about this on this stackoverflow)

Allowed token types:

  • eventOrganizer: for event organizers
  • familyOrganizer: for event family organizers
  • eventStats: for tools requiring event stats (such as conference walls)
  • familyStats: for family-wide tools requiring event stats (such as conference walls)

Dummy call sample:

curl --request GET \
  --url 'https://api-demo.voxxr.in/api/events/myEvt24/topTalks?token=eventOrganizer%3AmyEvt24%3A1234567-89ab-cdef-1234567890ab'
Example payload response 
{
  "dailyTopTalks": [
    {
      "date": "2025-01-02",
      "dayId": "thursday",
      "topTalks": [
        {
          "talkId": "talk1",
          "title": "A very interesting talk",
          "speakers": [
            {
              "id": "speaker1",
              "fullName": "John Doe",
              "companyName": "Acme inc",
              "photoUrl": ""
            }
          ],
          "start": "2025-01-02T11:30:00Z",
          "end": "2025-01-02T12:15:00Z",
          "format": "Conference",
          "language": "en",
          "room": "Room A",
          "track": "Java",
          "tags": [],
          "averageRating": 4.80,
          "numberOfVotes": 42
        }
      ]
    }
  ]
}

Get specific talk's detailed feedbacks

URIs:

  • Public events: GET {{baseUrl}}/api/events/{{eventId}}/talks/{{talkId}}/feedbacks?token={{secretToken}}&updatedSince={{updatedSinceISODatetime}}
  • Private events: GET {{baseUrl}}/api/spaces/{{spaceToken}}/events/{{eventId}}/talks/{{talkId}}/feedbacks?token={{secretToken}}&updatedSince={{updatedSinceISODatetime}}
Details

Params:

  • [path] baseUrl*, spaceToken*, eventId*: see Pre-requisites section
  • [path] talkId*: Talk id you want to retrieve detailed feedbacks
  • [query] secretToken*: see Pre-requisites section
  • [query] updatedSinceISODatetime (facultative): shows only feedbacks provided after this ISO-8601 datetime. When this query param is not provided, every feedbacks will be returned.

Important Note: this endpoint is ETag-friendly. It means that:

  • It will return an etag response header when calling it
  • You can pass this etag response header to your next request's X-If-None-Match (*) request header: if nothing has changed, an empty payload with HTTP status 304 Not Modified will be returned.

(*) X-If-None-Match custom header has to be used instead of standard If-None-Match header, because Firebase Hosting (which is used for Voxxrin API endpoints) is currently filtering out If-Not-Match header in firebase cloud functions (more about this on this stackoverflow)

Allowed token types:

  • eventOrganizer: for event organizers
  • familyOrganizer: for event family organizers

Dummy call sample:

curl --request GET \
  --url 'https://api-demo.voxxr.in/api/events/myEvt24/talks/talk1/feedbacks?token=eventOrganizer%3AmyEvt24%3A1234567-89ab-cdef-1234567890ab&updatedSince=2025-01-02T09:10:35Z'
Example payload response 
[
  {
    "eventId": "myEvt24",
    "talkId": "talk1",
    "feedbacks": [
      {
        "ratings": {
          "custom-rating": null,
          "linear-rating": 3,
          "bingo": [
            {
              "id": "1",
              "label": "Really enjoyed this"
            },
            {
              "id": "2",
              "label": "Awesome content"
            }
          ]
        },
        "lastUpdatedOn": "2025-01-02T10:06:56.523Z",
        "comment": null,
        "attendeePublicToken": "eec471c6-7384-4037-b7ed-91184452d7f8",
        "talkId": "talk1",
        "createdOn": "2025-01-02T10:06:55.623Z"
      }
    ]
  }
]

Get event's per-talk editor secret URLs

This endpoint allows conference organizer to share private URLs with their speakers so that they are able to see feedbacks on their talks in realtime.
This should also allow speakers to edit some part of their talks like, providing assets (such as slides URLs, or github repository) or updating some parts of their speaker profile (like, social media platforms).

URIs:

  • Public events: GET {{baseUrl}}/api/events/{{eventId}}/talksEditors?token={{secretToken}}&baseUrl={{voxxrinInstanceBaseUrl}}
  • Private events: GET {{baseUrl}}/api/spaces/{{spaceToken}}/events/{{eventId}}/talksEditors?token={{secretToken}}&baseUrl={{voxxrinFrontendBaseUrl}}
Details

Params:

  • [path] baseUrl*, spaceToken*, eventId*: see Pre-requisites section
  • [query] secretToken*: see Pre-requisites section
  • [query] voxxrinFrontendBaseUrl*: the Voxxrin frontend base url (like, https://app-demo.voxxr.in). This is particularly useful for white-labelled Voxxrin instances, so that your speakers keep using the same white-labelled Voxxrin instance than your attendees'

Important Note: this endpoint is ETag-friendly. It means that:

  • It will return an etag response header when calling it
  • You can pass this etag response header to your next request's X-If-None-Match (*) request header: if nothing has changed, an empty payload with HTTP status 304 Not Modified will be returned.

(*) X-If-None-Match custom header has to be used instead of standard If-None-Match header, because Firebase Hosting (which is used for Voxxrin API endpoints) is currently filtering out If-Not-Match header in firebase cloud functions (more about this on this stackoverflow)

Allowed token types:

  • eventOrganizer: for event organizers
  • familyOrganizer: for event family organizers

Dummy call sample:

curl --request GET \
  --url 'https://api-demo.voxxr.in/api/events/myEvt24/talksEditors?token=eventOrganizer%3AmyEvt24%3A1234567-89ab-cdef-1234567890ab&baseUrl=https%3A%2F%2Fapp-demo.voxxr.in'
Example payload response 
[
  {
    "eventId": "myEvt24",
    "secretToken": "bd575ec5-3c7e-43fe-82db-5fcb5dd16a39",
    "talkId": "talk1",
    "speakersFullNames": [
      "John Doe"
    ],
    "registrationUrl": "https://app-demo.voxxr.in/user-tokens/register?type=TalkFeedbacksViewer&spaceToken=&eventId=myEvt24&talkId=talk1&secretToken=bd575ec5-3c7e-43fe-82db-5fcb5dd16a39"
  },
  {
    "eventId": "myEvt24",
    "secretToken": "9dcec52f-a962-46e4-8a32-0fc1ae2d75f1",
    "talkId": "talk2",
    "speakersFullNames": [
      "Jane Doe"
    ],
    "registrationUrl": "https://app-demo.voxxr.in/user-tokens/register?type=TalkFeedbacksViewer&spaceToken=&eventId=myEvt24&talkId=talk2&secretToken=9dcec52f-a962-46e4-8a32-0fc1ae2d75f1"
  }
]

Refresh talk recording assets (from Youtube)

Allows to crawl Video Platforms (like Youtube) based on what is configured at your Conference Descriptor level, in order to try to match videos (based on their title) with your event's talks.

URIs:

  • Public events: POST {{baseUrl}}/api/events/{{eventId}}/refreshRecordingAssetsRequest?token={{secretToken}}
  • Private events: POST {{baseUrl}}/api/spaces/{{spaceToken}}/events/{{eventId}}/refreshRecordingAssetsRequest?token={{secretToken}}
Details

Params:

  • [path] baseUrl*, spaceToken*, eventId*: see Pre-requisites section
  • [query] secretToken*: see Pre-requisites section

Allowed token types:

  • eventOrganizer: for event organizers
  • familyOrganizer: for event family organizers

Dummy call sample:

curl --request POST \
  --url 'https://api-demo.voxxr.in/api/events/myEvt24/refreshRecordingAssetsRequest?token=eventOrganizer%3AmyEvt24%3A1234567-89ab-cdef-1234567890ab'
Example payload response 
{
  "summary": {
    "updates": "1 talk URLs have been updated  (out of 25 matched talks): 42031",
    "matchings": {
      "message": "There are 14 talks and 1 videos which didn't matched",
      "unmatchedElements": [
        {
          "type": "Video",
          "label": "Youtube video title here"
        },
        {
          "type": "Talk",
          "label": "[talk1] A super talk title here (Speaker name 1)",
          "format": "Conference"
        }
      ]
    }
  },
  "matchedTalks": [
    {
      "score": 0.98,
      "titles": {
        "talkWithSpeakers": "another super talk - speaker name 2",
        "video": "another super talk by speaker name 2"
      },
      "talk": {
        "id": "talk2",
        "title": "Another super talk",
        "format": {
          "duration": "PT55m",
          "id": "1",
          "title": "Keynote"
        },
        "speakers": [
          {
            "fullName": "Speaker Name 2"
          }
        ]
      },
      "video": {
        "id": "26pc319OsA4",
        "publishedAt": "2025-01-02T16:09:14Z",
        "title": "Another super talk by Speaker name 2",
        "duration": "PT52M"
      }
    }
  ],
  "unmatchedTalks": [
    {
      "talk": {
        "id": "talk3",
        "title": "Still another super talk",
        "format": {
          "duration": "PT50m",
          "id": "2",
          "title": "Conference"
        },
        "speakers": [
          {
            "fullName": "Speaker name 3"
          }
        ]
      },
      "highestScoreInvalidVideo": {
        "bestScore": 0.397,
        "bestScoreFrom": "titleWithSpeakers",
        "titleWithSpeakersSimilarityScore": 0.397,
        "titleOnlySimilarityScore": 0.394,
        "titles": {
          "talkWithSpeakers": "still another super talk - speaker name 3",
          "video": "generate your doc with chatgpt by speaker name 4"
        },
        "titleIncludingSpeakerNamesRatio": 0,
        "video": {
          "id": "WXXsS6k2qMI",
          "publishedAt": "2025-01-02T05:01:23Z",
          "title": "Generate your doc with ChatGPT by Speaker Name 4",
          "duration": "PT27M57S"
        }
      }
    }
  ],
  "unmatchedYoutubeVideos": [
    {
      "id": "WXXsS6k2qMI",
      "publishedAt": "2025-01-02T10:54:54Z",
      "title": "Generate your doc with ChatGPT by Speaker Name 4",
      "duration": "PT27M57S"
    }
  ]
}

Update multiple rooms statistics (like: capacity)

This allows to update multiple rooms' remaining capacity in realtime, so that a realtime room capacity indicator is displayed to your attendees.

URIs:

  • Public events: POST {{baseUrl}}/api/events/{{eventId}}/rooms/stats?token={{secretToken}}
  • Private events: POST {{baseUrl}}/api/spaces/{{spaceToken}}/events/{{eventId}}/rooms/stats?token={{secretToken}}
Details

Params:

  • [path] baseUrl*, spaceToken*, eventId*: see Pre-requisites section
  • [query] secretToken*: see Pre-requisites section

Allowed token types:

  • eventOrganizer: for event organizers
  • familyOrganizer: for event family organizers
  • eventRoomStatsContributor: for external systems aimed at only providing room stat indication for a specific event
  • familyRoomStatsContributor: for external systems aimed at only providing room stat indication for all events belonging to an event family

Dummy call sample:

curl --request POST \
  --url 'https://api-demo.voxxr.in/api/events/myEvt24/rooms/stats?token=eventOrganizer%3AmyEvt24%3A1234567-89ab-cdef-1234567890ab' \
  --header 'content-type: application/json' \
  --data '{
  "roomsStats": [{
    "roomId": "room1",
    "capacityFillingRatio": 0.5, 
    "recordedAt": "2025-01-02T06:57:00Z"
  }, {
    "roomId": "room2",
    "capacityFillingRatio": 0.70, 
    "recordedAt": "2025-01-02T06:57:00Z"    
  }]
}'
Example payload response 
{
  "roomsStats": {
    "room1": {
      "persistedAt": "2025-01-02T06:58:42Z",
      "capacityFillingRatio": 0.5,
      "recordedAt": "2025-01-02T06:57:00Z",
      "roomId": "room1"
    },
    "room2": {
      "persistedAt": "2025-01-02T06:58:42Z",
      "capacityFillingRatio": 0.7,
      "recordedAt": "2025-01-02T06:57:00Z",
      "roomId": "room2"
    },
    "room3": {
      "persistedAt": "2025-01-02T06:55:34Z",
      "capacityFillingRatio": "unknown",
      "recordedAt": "2025-01-02T06:43:04Z",
      "roomId": "room3"
    }
  }
}

Update single room statistics (like: capacity)

This allows to update single room' remaining capacity in realtime, so that a realtime room capacity indicator is displayed to your attendees.

URIs:

  • Public events: POST {{baseUrl}}/api/events/{{eventId}}/rooms/{{roomId}}/stats?token={{secretToken}}
  • Private events: POST {{baseUrl}}/api/spaces/{{spaceToken}}/events/{{eventId}}/rooms/{{roomId}}/stats?token={{secretToken}}
Details

Params:

  • [path] baseUrl*, spaceToken*, eventId*: see Pre-requisites section
  • [path] roomId*: the room id you want to update statistics to
  • [query] secretToken*: see Pre-requisites section

Allowed token types:

  • eventOrganizer: for event organizers
  • familyOrganizer: for event family organizers
  • eventRoomStatsContributor: for external systems aimed at only providing room stat indication for a specific event
  • familyRoomStatsContributor: for external systems aimed at only providing room stat indication for all events belonging to an event family

Dummy call sample:

curl --request POST \
  --url 'https://api-demo.voxxr.in/api/events/myEvt24/rooms/room1/stats?token=eventOrganizer%3AmyEvt24%3A1234567-89ab-cdef-1234567890ab' \
  --header 'content-type: application/json' \
  --data '{
  "capacityFillingRatio": 0.5, 
  "recordedAt": "2025-01-02T06:57:00Z"
}'
Example payload response 
{
  "roomsStats": {
    "roomId": "room1",
    "recordedAt": "2025-01-02T06:57:00Z",
    "persistedAt": "2025-01-02T06:58:42Z",
    "capacityFillingRatio": 0.5,
    "valid": {
      "forTalkId": "talk1",
      "until": "2025-01-02T07:21:15.000Z"
    }
  }
}
Clone this wiki locally