Invite discussions

Each invite can have its own discussion for event-specific questions, changes and coordination.

Discussion availability is controlled globally by the invited VTC. It cannot be changed for an individual invite or configured differently for specific inviting VTCs.

Availability modes

Mode	Behaviour	Default
Always on	Both the inviting VTC and the invited VTC can start and reply to messages on any invite.	✓
Invitee-led	The invited VTC must start the discussion. Once they have sent the first message, the inviting VTC can reply and the discussion becomes two-way.
Disabled	Discussions are unavailable for all invites. No messages can be sent by either VTC, including through the API.

Sending messages through the API

Messages sent through the API follow the same discussion rules as messages sent through event thing.

The API token determines which VTC is sending the message.

Always on

When the invited VTC has discussions set to Always on, either side of an invite can send messages through the API at any time.

This means a token belonging to either the inviting VTC or the invited VTC can start the discussion.

Invitee-led

When the invited VTC has discussions set to Invitee-led, only the invited VTC can start the discussion.

An API token belonging to the invited VTC can therefore send the first message:

POST /v1/invites/{invite_id}/messages

Once the invited VTC has sent the first message, the discussion becomes two-way and the inviting VTC can reply.

If a token belonging to the inviting VTC attempts to send the first message, the request is rejected:

403 Forbidden

{
  "error": {
    "code": "discussion_not_started",
    "message": "The invited VTC must start this discussion."
  }
}

After the invited VTC has started the discussion, API tokens belonging to either VTC can send messages.

Disabled

When discussions are Disabled, neither side can send messages through the API.

403 Forbidden

{
  "error": {
    "code": "discussions_disabled",
    "message": "Discussions are disabled for this VTC."
  }
}

Send a message

Send a message to an invite discussion using:

POST /v1/invites/{invite_id}/messages

{
  "body": "We've changed the meetup time to **18:30 UTC**.\n\nPlease let your drivers know."
}

The message is sent as the VTC authorised by the API token.

The authorised VTC must be either the inviting VTC or the invited VTC for the specified invite.

Markdown

Message bodies support Markdown.

{
  "body": "A few updates for the convoy:\n\n- Meetup is now **18:30 UTC**\n- Departure is unchanged\n- Please use slot **12**"
}

Returned message bodies should be treated as untrusted content. Clients should either disable raw HTML when rendering Markdown or sanitise the rendered output before displaying it.

Events

Blocking