What Jitsi reservation system integration controls and how it works
If your goal is for meeting rooms to exist only for booked slots, the Jitsi reservations Prosody module is the component that makes that happen. Before a conference is created, the module calls an external REST API, and Prosody enforces the conference duration that the API returns, ending the conference when that limit is exceeded. The booking tool answers the question "is this room booked, and for how long?" while Jitsi decides whether to open the room and when to close it. The integration is configured on the self-hosted Jitsi Meet deployment, in its Prosody settings, not inside the booking or scheduling product. That split matters for ownership. Your booking system needs an endpoint that answers the request in the format Jitsi expects, and your Jitsi administrators own the Prosody configuration, the timeouts, the retry behavior and the secrets used to call the API. Only the /conference endpoint is supported, so a design that expects Jitsi to call other paths, such as separate room or user lookups, will not work as documented. Confirm the exact request and response contract against the current handbook before building anything on your booking side. The settings that shape behavior are reservations_api_timeout, which defaults to 20 seconds, reservations_api_headers for passing authentication tokens to the API, and reservations_api_retry_count, which defaults to 3. These defaults are the starting point for your planning, not a recommendation for your network. A short timeout can cause a legitimate booked meeting to fail to open during a slow booking-system response, while a long one delays every meeting that depends on a lookup. Decide what should happen when the API is unreachable: whether rooms fail closed, which is safer for access control, or fail open, which keeps meetings running but weakens the booking rule. The response can do more than set a duration. When the matching reservations_enable options and Prosody modules are turned on, the reservation response can also set a maximum number of occupants, enable the lobby, or set a room password. Each of these adds a dependency: the Prosody modules must be deployed, the booking system must return the fields consistently, and your team must test each path. Enable only the controls your policy requires, and write down which system is the source of truth for each one. Before go-live, plan tests for the cases that go wrong in practice: a meeting started early, a meeting that overruns its slot, an API outage, a rejected request, and a room with no booking at all. Also confirm how your team will monitor the Prosody logs and the booking API so that a failed lookup is visible to someone who can act on it.
What you need in place before the reservation integration
The reservation integration only works when the Jitsi stack, its public certificate and the booking system are all ready to talk to each other. Check these four areas before any Prosody configuration starts, because a gap in any one of them shows up later as rooms that fail to open or meetings that drop mid-session.
A working self-hosted Jitsi Meet
Confirm a complete Jitsi Meet install works end to end before adding the reservation module. On Debian, the quick start supports Debian 12 (Bookworm) or newer and Ubuntu 24.04 or newer, and requires OpenJDK 17. If you run the official Docker setup instead, the web, Prosody, Jicofo and Videobridge containers must all be healthy. Test a plain room from two browsers on separate networks first, so you know any later failure belongs to the reservation layer.
A trusted domain certificate
The Jitsi handbook states that HTTPS with a proper domain certificate is necessary for working audio and video, and it warns that self-signed certificates cause problems, especially on mobile clients. Decide who issues and renews the certificate for the meeting hostname, and confirm the renewal process runs without manual steps. Reservation calls do not replace this requirement, so an expired certificate will break meetings even when bookings are correct.
Open ports and network paths
The quick start needs 80/TCP and 443/TCP for the web app, and 10000/UDP for media through the Videobridge. Port 5349/TCP serves as TCP fallback and 3478/UDP for STUN is optional, so decide whether your firewall and NAT policy allow them. Verify each port from outside your network, not only from the host. Confirm with your network team which path the media traffic takes through any load balancer or perimeter device.
A reachable endpoint for /conference
Prosody calls your booking system over HTTP before creating a conference, so the Jitsi server must reach the booking API endpoint for the /conference path. Confirm which host makes the call, whether it can resolve the booking system's name and whether outbound rules, proxies or allow lists permit that request. Ask the booking system's vendor or internal team whether the endpoint accepts requests from the Jitsi server's address and whether it returns the conference duration in the response format the handbook expects.
A named owner for the shared API token
The reservations module can send authentication headers to the booking API, so a shared secret protects the call. Assign one named owner, usually a platform or identity team member, who controls where the token is stored, when it rotates and who may read it. Record how the token reaches the Jitsi configuration, because it should not sit in a shared document or chat history. Without a named owner, token rotation tends to be skipped until an outage forces it.
A test environment separate from production
Build a second Jitsi instance and a non-production booking system so you can test room opening, early closing and timeouts without affecting live meetings. Use a separate hostname and certificate for the test site. Plan test cases for a booked room, an unbooked room, a booking that expires during a call and a booking API that times out. The Prosody reservation options, including the default 20 second timeout and 3 retries, should be tested with your actual network latency before production use.
How the booking request flows from the browser to Prosody
A room should open only after the booking system has approved it, and Prosody is the component that asks. When a participant opens a room URL in the browser, the web app loads and starts its signaling session with Prosody, the XMPP server in your Jitsi Meet deployment. With the reservations module enabled, Prosody sends a request to the external reservation REST API before the conference is created. The browser does not call the booking system directly, so the endpoint and its credentials stay on the Prosody host. Your team should confirm in the handbook exactly which Prosody settings control this check and where they are configured on your install method.
The response decides two things: whether the room opens and how long it stays open. If the reservation is valid, Prosody allows the conference to start and enforces the duration the response returns. When that limit is exceeded, Prosody ends the conference. If the API refuses the request or cannot be reached, the room does not open, so the availability of the booking system becomes part of the availability of your meetings. Plan for that dependency using the documented options: the request timeout defaults to 20 seconds and the retry count defaults to 3. Confirm in the handbook how a refusal and a timeout differ, because participants and operators will see different outcomes in each case.
Two details must be settled before anyone builds the booking side of the integration. The first is how a room name in the browser URL maps to the reservation request, including which part of the room identifier the API receives and how the booking system matches it to a booking record. The second is what the response must contain for Prosody to act on it. The handbook's reservation page is the reference for both, and this section does not assume any request or response field names. Record both answers in the integration design so that the booking team and the Jitsi operators use the same definitions, and test a few sample bookings against them before go-live.
The response can also set maximum occupants, enable the lobby or set a room password, but only when the matching reservations_enable options and Prosody modules are enabled on the server. Decide early which of these your booking data will carry, because each one adds a dependency. A booking field that is empty, stale or formatted differently from what Prosody expects can change how the room behaves for participants. Before go-live, test an expired booking, a booking with a room password, and a booking cancelled after the room is already open. Write down what participants see in each case, and make sure the support team knows it too.
How to configure the reservation integration step by step
This sequence takes a self-hosted Jitsi Meet from a working HTTPS deployment to one where rooms open only with a booking and close when the booked time runs out. Each step ends with a check you can run before moving on.
Confirm the Jitsi deployment and certificate
Your infrastructure or platform team confirms that the Jitsi Meet site loads over HTTPS on a proper domain name with a certificate from a trusted authority. The Jitsi handbook states that HTTPS with a proper domain certificate is necessary for working audio and video, and that self-signed certificates cause problems, especially on mobile clients. Before any reservation work starts, the team should confirm that an unbooked test conference can be created and joined from a desktop browser and a mobile client. The step is complete when both clients connect with audio and video and the certificate chain validates from outside your network.
Enable the reservations module in Prosody
The Prosody administrator enables the reservations module for your conference domain in the Prosody configuration, then turns on any reservations_enable options the booking system will drive, such as maximum occupants, lobby or room password. The handbook notes that these options take effect only when the corresponding Prosody modules are also enabled, so enable those modules in the same change. Validate the configuration syntax, restart Prosody, and read the startup log. Confirm the exact file path and option names against the reservation section of the handbook for your installed version. The step is complete when Prosody starts with no module load errors and the module appears as loaded.
Set timeout, headers and retry count
The Prosody administrator sets three options that control how Prosody talks to the booking system. The reservations_api_timeout option defaults to 20 seconds, reservations_api_retry_count defaults to 3, and reservations_api_headers carries the authentication token that the booking system expects on each request. Keep the defaults until you have measured your booking system's response times under load, then change them in a staging environment first. Confirm the header format in the handbook, because a malformed header is a common cause of rejected requests. The step is complete when the effective values match the plan and a deliberately wrong token is rejected by the booking system and logged by Prosody.
Point the module at the booking endpoint
The Prosody administrator points the reservations module at the base address of the booking system's /conference endpoint. The handbook documents /conference as the only supported endpoint, so the booking system must expose it over HTTPS and be reachable from the Prosody host through the firewall rules you set. Agree on which team owns the endpoint and its certificate, since a certificate expiry here blocks all room creation. The step is complete when a test join to a room triggers a request from the Prosody host, and the booking system's access log shows that request with the room name it received.
Implement the conference response in the booking system
The booking system team builds the logic that answers the /conference request. For a room with an active booking, the response returns the conference duration that Prosody will enforce, and it can also set maximum occupants, enable the lobby or set a room password when the matching reservations_enable options are on. For a room with no active booking, the response must refuse the conference. Build the response schema from the handbook's reservation documentation, and keep the booking lookup, time window and room naming rules in the booking system where your scheduling data lives. The step is complete when staging requests for a booked room and an unbooked room return the expected responses.
Run booked and unbooked room tests
The integration team runs three test cases in staging before any production use. First, join a room with no booking and confirm that entry is refused. Second, join a room with a valid booking and confirm that participants are admitted and that the lobby, occupant limit or password behave as the response specified. Third, let a short booking expire during a live conference and confirm that Prosody ends the conference when the duration is exceeded. Also test what happens when the booking system is unreachable, so you know how retries and the timeout behave before users depend on them. Record the results for each case. The step is complete when all three cases match the expected outcome and the results are filed with the change record.
Which booking data maps to which Jitsi reservation settings
This table pairs each common booking system field with the reservation response setting it is most likely to feed in a Jitsi integration. Read each row as a design decision, because the optional settings only take effect when the matching reservations_enable option and Prosody module are both enabled. Confirm exact field names and value formats in the Jitsi reservation handbook before you write the mapping.
| Booking system field | Jitsi reservation setting | What to confirm before building |
|---|---|---|
| Booking identifier | Used to match the API call to one booking | Which identifier the /conference request carries, and how your system looks it up |
| Room | Identifies the conference the reservation applies to | That the room name your booking system sends matches the Jitsi room name exactly |
| Start and end time | Duration in the response, enforced by Prosody | The duration unit and format, and that Prosody ends the conference when the limit passes |
| Expected attendee count | Maximum occupants | Whether the maximum occupants option and module are enabled, and how the limit is applied |
| Waiting-room need | Lobby | Whether the lobby option and module are enabled, and who admits guests when the lobby is on |
| Access code | Room password | Whether the room password option and module are enabled, and how the code is formatted |
| Slow or failed API response | Request timeout and retry count | Handbook defaults of 20 seconds and 3 retries, and what happens to the room if all retries fail |
How to secure the reservation API connection
Jitsi's reservations module calls your booking system before a conference starts, so this connection decides who can open a room and for how long. The cards cover the token, the network path, the certificate, the permissions in the response, failure handling and logging. Jitsi's DTLS-SRTP encryption protects audio and video, but it does not cover reservation API traffic, so this channel needs its own controls.
Protect the API token
Store the token that Prosody sends through reservations_api_headers in a secrets manager or in a file readable only by the Prosody service account. Issue a token used only for reservation lookups, and plan a rotation procedure that updates the booking system and the Prosody configuration in one change window. Confirm with your booking vendor whether the token can be scoped to the /conference endpoint, since that is the only endpoint Jitsi calls.
Restrict the endpoint to the Jitsi path
Allow connections to the booking API only from the Prosody host or the network segment where it runs, and deny other sources at the firewall or security group. Jitsi calls the API before each conference is created, so an endpoint open to any source adds exposure without serving meetings. Test the rule from an address outside the allowed range, and confirm how the call behaves against reservations_api_timeout, which defaults to 20 seconds.
Serve the booking service over HTTPS
Serve the booking service over HTTPS with a certificate issued by a trusted authority for its hostname. The Jitsi handbook says a proper domain certificate is necessary for working audio and video and warns that self-signed certificates cause problems, especially with mobile clients. Confirm that Prosody validates the full certificate chain, and monitor expiry so a lapsed certificate does not stop rooms from opening.
Limit what the response can grant
Treat each reservation response as a set of grants. The response can set maximum occupants, enable the lobby and set a room password, but only when the matching reservations_enable options and Prosody modules are turned on. Enable only the grants your booking workflow needs, validate the values your booking service returns, and test a booking for each grant in a staging room before production use.
Decide how failures behave
Define what happens when the booking API times out, returns an error or is unreachable. Prosody retries the request according to reservations_api_retry_count, which defaults to 3, and the outcome of the final attempt decides whether the room opens. Document the choice with the meeting owners, and test both an unreachable API and a slow API so staff know what participants will see.
Log every reservation decision
Record each reservation decision with the room name, the request time, the outcome and the duration returned, so support staff can explain why a room opened, stayed closed or ended. Confirm that the log also captures the end of a conference when Prosody enforces the duration limit. Keep the token out of log entries, and agree on retention with your compliance owner before go-live.
Deciding what happens when the booking API is slow or down
Before go-live, the team must decide whether a failed reservation lookup blocks the room or lets it open. The Jitsi reservations Prosody module queries an external REST API before a conference is created, and only the /conference endpoint is supported. Two settings control how Prosody waits on that call: reservations_api_timeout, which defaults to 20 seconds, and reservations_api_retry_count, which defaults to 3. These defaults are a starting point that someone on your team should review. Each value determines how long a participant waits at the door and how often the booking system is called during an incident, so set both deliberately and record the reason for each value.
The core trade-off is availability against enforcement. A fail-open setting keeps meetings running when the booking system is slow, but rooms may run without a valid booking and the duration limit may not be enforced. A fail-closed setting guarantees that no room opens without a confirmed booking, but a booking outage then stops meetings across the organization, including meetings that were properly scheduled. A telehealth provider, an internal audit group and a public training team will weigh these differently. Ask the booking system owner how a failed lookup appears to them, since it may surface as a timeout, an error code or an empty response, and Jitsi's handling of each case should be confirmed in advance.
Whichever mode is chosen must be written into the operating runbook, not left only in a configuration file. The runbook should name the owner of the decision, the timeout and retry values in force, the behavior on lookup failure, who is alerted when lookups fail, and how an on-call engineer can confirm which mode is active. It should also cover a booking system outage: who may switch modes, how the change is approved, how it is reverted, and how users are told. Review the runbook whenever the booking API changes, the authentication headers rotate or the Jitsi version is upgraded.
Before go-live, run load and outage tests against the booking endpoint from the same network path that Prosody uses. Load tests should show how lookup latency changes as conference creation rises during peak scheduling periods. Outage tests should simulate a slow response, a hard error and an unreachable endpoint, then confirm that the chosen mode behaves as the runbook describes and that rooms close when the returned duration expires. Keep the results with the configuration used for each run. Exact behavior, including how retries are counted and what a participant sees during a retry, should be confirmed in the Jitsi handbook for the installed version before the test plan is finalized.
Common reservation integration failures and their fixes
This table lists the failures most often seen when Jitsi reads bookings from an external reservation API, with the likely cause and the first check for each. Work through the rows in order, since a broken API call or missing module often causes several symptoms at once. Confirm every value against your own Prosody configuration and booking system before changing production settings.
| Failure | Likely cause | First fix to check |
|---|---|---|
| Rooms open without a booking | The reservations module is not loaded for the conference domain, so Prosody never queries the booking API before creating the room. | Confirm the reservations module is enabled in the Prosody configuration for the domain serving meetings, then restart Prosody and test an unbooked room name. |
| Valid bookings are refused | The room name sent to the API differs from the name in the meeting URL because of letter case, spacing, or URL encoding. | Compare the room name stored in the booking system with the room segment of a working meeting URL, and normalize both to the same format. |
| Meetings end early | The duration returned by the API is shorter than the booked end time, often from a time zone offset or a unit mismatch in the booking system. | Call the endpoint for a test booking and compare the duration field in the response with the booked start and end times. |
| Timeouts under load | The booking API responds more slowly than the configured timeout, and retries add to the delay when many rooms open at once. | Measure the booking API response time under typical peak load, then compare it with the configured reservations_api_timeout (default 20 seconds) and reservations_api_retry_count (default 3). |
| Authentication errors from the token header | The header name in reservations_api_headers does not match what the booking API expects, or the token is expired, missing or copied with extra whitespace. | Send a test request from the Prosody host using the same header name and token value, and check the API log for the rejection reason. |
| Rooms missing lobby or password settings | The reservations_enable options are off, the matching Prosody module is not enabled, or the API response omits the field. | Confirm both the reservations_enable option and its Prosody module are enabled, then inspect a raw API response to check that the lobby or password fields are present. |
| Invalid certificates on the booking endpoint | The booking endpoint uses a self-signed or private CA certificate that the Prosody host does not trust, so the TLS handshake fails. | Test the TLS connection from the Prosody host, then install the issuing CA into the host trust store or replace the endpoint certificate with one from a trusted CA. |
Questions buyers ask before hiring help with Jitsi reservation integration
What drives the cost of a Jitsi reservation integration project?
The main cost drivers are the number of booking systems, the custom response logic, the failure-policy design and the testing scope. Each booking system adds its own API contract, authentication model and data mapping, so a second system repeats much of the discovery and test work of the first. Custom response logic matters because the reservation API response can set duration, maximum occupants, lobby and room password values, and every rule that sets those values needs specifying and testing. Failure-policy design decides what happens when the booking API is slow or unavailable, and the handbook exposes the timeout and retry settings that shape that behavior. Testing scope grows with the number of booking states you need to cover. Most of the cost is one-time build and test work, while upgrades and maintenance recur. Ask any quote to itemize discovery, build, testing and handover separately.
Can our team build a Jitsi reservation integration from the handbook alone?
Yes, a team with Linux, Prosody and REST API experience can often build the core integration from the handbook. The reservation documentation covers the supported /conference endpoint, the timeout, headers and retry options, and the response fields that set duration and room rules. It does not design how your booking system signals a cancelled or moved booking, how expired tokens are handled, or how edge cases such as a conference running past its end time are tested. Those decisions belong to your team or a partner. The Jitsi scalable setup guide warns that scalable infrastructure is not a task for beginning administrators, so a team new to Jitsi operations should weigh that alongside the integration work. Before deciding, confirm who owns the Prosody module configuration, the API credentials and the test plan.
How long does a Jitsi reservation integration take to build?
The schedule depends mainly on how ready the booking system is. The Jitsi side needs a working REST endpoint that returns conference details, so the Jitsi work itself is usually configuration, response mapping and testing. If the booking system already has a documented API, test data and a sandbox, the build moves quickly. If the API is undocumented, lacks a test environment or needs changes from another team or vendor, those dependencies set the timeline. No fixed duration applies across all environments. Ask for a timeline in the written scope that lists each dependency, the owner of each one and what must be ready before build starts. The plan should also include a staging Jitsi server connected to a copy of the booking API.
What do we need to provide before an integration engagement starts?
You need to provide API access to the booking system, a test environment that returns responses shaped like production, and named owners for each credential. If production data cannot be used in testing, provide representative test data instead. The reservation setup passes authentication tokens in request headers, so someone must own those tokens, rotate them and store them in your secrets tooling. The handbook says HTTPS with a proper domain certificate is necessary for working audio and video and warns that self-signed certificates cause problems, especially on mobile clients, so assign an owner for the certificate and its renewal. You also need a staging Jitsi host, a change window for production and a contact who can confirm booking rules. Record these owners in the scope document so the work does not stall while access is arranged.
What happens to a Jitsi conference when the booking time runs out?
Prosody enforces the conference duration returned by the reservation API and ends the conference when that limit is exceeded. The module queries your booking system before a conference is created, so the duration the API returns sets the limit for that meeting. Engineers should confirm how participants see the approaching end of the meeting, how the booking system represents extensions and what happens when a booking changes while a conference is already in progress. The handbook documents enforcement at the Prosody layer but does not describe participant messaging or an extension workflow, so those need design. Test a meeting that runs over its slot, a booking extended mid-call and a cancellation before go-live.
What ongoing work recurs after a Jitsi reservation integration goes live?
Upgrades are the main recurring task. Jitsi Meet publishes tagged stable builds, and the Docker setup moved to rootless containers with read-only filesystems starting with stable-11146, which changed directory layouts that custom configuration may depend on. Each upgrade needs a check that the reservations module and its configuration still load and that the API contract with your booking system still matches. Other recurring work includes rotating API tokens, renewing the domain certificate, reviewing timeout and retry settings after booking system changes and keeping staging aligned with production. Confirm who performs each task and how often, and ask for support or retainer terms in writing. DeployOpen offers ongoing support, upgrades and testing as retainers, and the scope of those terms is set in writing.
Which failure settings should we decide before the integration is built?
Decide what happens when the booking API is slow, unavailable or returns an error, because the module's answer determines whether a conference opens. The reservations_api_timeout option defaults to 20 seconds, and reservations_api_retry_count defaults to 3, so a slow booking system can delay or block room creation for participants. Choose whether a room should fail closed or fail open, then confirm which behavior your build supports against the handbook. Record the decision with the business owner, since it affects user trust and, in regulated settings, compliance obligations. Also decide how errors are logged and who receives alerts. Testing should cover timeouts, exhausted retries and malformed responses.
How DeployOpen scopes, delivers and supports the reservation integration
DeployOpen plans and implements the reservation integration inside infrastructure you control, so Jitsi rooms open only for booked slots and close when the booked time ends. The work is fixed-scope, with the reservation API contract, Prosody configuration and test evidence agreed in writing before build starts.
How we scope
- Written scope names the booking system, its reservation API endpoints and the authentication headers Prosody will send.
- Scope records how the /conference response will set duration, maximum occupants, lobby and room password options.
- Scope agrees timeout and retry settings for the reservations module, and the behavior when the booking API is unreachable.
How we build
- We configure the Jitsi reservations Prosody module and the reservation endpoint on your Jitsi host, using the documented options.
- We build or adapt the booking-side responder so it returns conference duration and access settings for each booked room.
- We test booked, unbooked, expired and API-failure cases in a non-production Jitsi instance before any change reaches users.
How we hand over
- Handover includes configuration files, the API contract, a test script and a record of every reservation option in use.
- Operators receive a runbook covering timeout and retry tuning, credential rotation for the reservation API and log review steps.
- Your team gets a walkthrough of how an expired reservation ends a conference, so support staff can explain it to meeting hosts.
How we support
- Ongoing support, upgrades and regression testing for the integration are available as a retainer after handover.
- Retainer work can cover Jitsi version changes, booking-system API changes and reviews of reservation module settings.
- Ask in your quote how changes to the booking system and Jitsi releases will be tested and who approves them.
