-
Notifications
You must be signed in to change notification settings - Fork 15
API User Services
The services API allows users to search for services and add them to conversations in the form of bots. An overview of the concepts of services and service providers can be found here.
The public service directory is located under the /services endpoint and
can be browsed for services by their assigned tags, names, or a combination
of both. A search query must use the GET HTTP method and mention at least
one tag. The result of a search query is a JSON response with a list of
service profiles, lexicographically sorted by their names.
Tags are specified using the tags query parameter. The abstract syntax accepted
by the query parameter in informal EBNF can be described as follows:
AnyTags ::= AllTags {"," AllTags}
AllTags ::= tag {"." tag}
Thereby
-
{}denotes repetition and","and"."are literals. -
AnyTagsis a logical disjunction (i.e. OR) of 1 to 3AllTags. -
AllTagsis a logical conjunction (i.e. AND) of 1 to 3 tags. - A
tagis any valid service tag.
A service name can be specified using the start query parameter and performs
a simple prefix match (case-insensitive), returning only those services whose names
come after the specified start name in lexicographic order.
Get services tagged with either quiz or sports.
> GET /services?tags=quiz,sports
Get services tagged with both quiz and sports.
> GET /services?tags=quiz.sports
Get services tagged with either both quizand sports, or entertainment.
> GET /services?tags=quiz.sports,entertainment
Get services tagged with both quiz and sports, having names starting with
Foot.
> GET /services?tags=quiz.sports&start=Foot
A provider profile can be obtained by sending a GET request to
the /providers/:pid endpoint, where :pid is a placeholder for
the provider ID. The JSON response contains the following attributes:
-
id(String): The ID of the provider. -
name(String): The name of the provider. -
email(String): The email address of the provider. -
url(String): The homepage URL of the provider. -
description(String): The description of the provider.
Example:
> GET /providers/:id
< 200 OK
< Content-Type: application/json
<
< {
< "id": "19c092cb-27cf-42f9-812e-a10de4f2dcae",
< "name": "Wire Swiss GmbH",
< "email": "[email protected]",
< "url": "https://wire.com/",
< "description": "The Wire Team"
< }
Service profiles can be obtained by sending a GET request to
one of /providers/:pid/services or /providers/:pid/services/:sid
to obtain a list of service profiles or a specific service profile
from a provider, with :pid and :sid being placeholders for the
provider and service IDs, respectively.
A service profile is a JSON object with the following attributes:
-
id(String): The ID of the service. -
provider(String): The ID of the provider that owns the service. -
name(String): The name of the service. -
description(String): The description of the service. -
assets(Array): A list of profile assets attached to the service. -
tags(Array): A list of tags assigned to the service. -
enabled(Boolean): Whether the service is enabled. A service that is not enabled is currently unavailable.
Example:
> GET /providers/746f2ee2-cafa-4d0c-b66e-7eafe7a1f75c/services
< 200 OK
< Content-Type: application/json
<
< [
< {
< "id": "75c5740e-3d01-46c8-be94-db2f09519361",
< "provider": "19c092cb-27cf-42f9-812e-a10de4f2dcae",
< "name": "Otto",
< "description": "Otto The Bot",
< "assets": [{"type": "image", "key": "3-1-cb21f0ce-6bd4-400e-9776-26ad5dd7cd62"}],
< "tags": ["tutorial", "entertainment"],
< "enabled": true
< }
< ]
Bots are constrained users that act as an interface for communication
with an external service. Bots can be distinguished from regular users
both from the user profile and the conversation member list via the
presence of a service attribute, which is a reference to the service
and provider operating the bot in form of a JSON object with the following
attributes:
-
id(String): The service ID. -
provider(String): The provider ID.
To add a service bot to a conversation, send a POST request to
/conversations/:cnv/bots, where :cnv is a placeholder for the
conversation ID. The authenticated user performing the request must
be a member of the conversation and the JSON request body contain
the following attributes:
-
provider(String): The provider ID of the desired service. -
service(String): The ID of the service from which to request a bot. -
locale(String, Optional): The preferred locale for the bot, in form of an IETF language tag. If not set, the locale of the authenticated user is used.
A successful response contains the following attributes in the JSON response body:
-
id(String): The user ID of the bot. -
client(String): The client ID of the bot. -
name(String): The name of the bot. -
accent_id(Number): The accent colour ID of the bot. -
assets(Array): The profile assets of the bot. -
event(Object): The member-join event that is sent to all other clients in the conversation.
Upon receiving a successful response, a new bot will have been added as a member
of the conversation, resulting in a conversation.member-join message to be sent
to all other members, including the new bot.
If the service imposes a limit on the number of bots per conversation,
a 409 Conflict error response with the JSON error label too-many-bots
is returned.
If the service is currently disabled, a 403 Forbidden error response with
the JSON error label service-disabled is returned.
If the service is unavailable or incorrectly configured, a 502 Bad Gateway
error response is returned.
Example:
> POST /conversations/0fa26937-1c2b-4aef-8556-da0fb3ec882d/bots
> Content-Type: application/json
>
> {
> "provider": "19c092cb-27cf-42f9-812e-a10de4f2dcae",
> "service": "75c5740e-3d01-46c8-be94-db2f09519361"
> }
>
< 201 Created
< Content-Type: application/json
<
< {
< "id": "d7473851-c0bf-4963-8df4-a0ed7c53d124",
< "client": "a1b2c3b4d5",
< "name": "Otto",
< "accent_id": 1,
< "assets": [{"type": "image", "key": "3-1-cb21f0ce-6bd4-400e-9776-26ad5dd7cd62"}],
< "event": {
< "type": "conversation.member-join",
< "conversation": "0fa26937-1c2b-4aef-8556-da0fb3ec882d",
< "from": "62c2157d-2081-46f0-b8aa-088d7a48142d",
< "time": "2016-08-16T13:29:14.123Z",
< "data": {"user_ids": ["d7473851-c0bf-4963-8df4-a0ed7c53d124"]}
< }
< }
To remove a bot from a conversation, send a DELETE request to
/conversations/:cnv/bots/:bot, where :cnv and :bot are placeholders
for the conversation ID and bot ID, respectively. The authenticated user
performing the request must be a member of the conversation.
Upon receiving a successful response, the bot will have been removed from the
conversation, resulting in a conversation.member-leave message to be sent
to all other members, including the removed bot.
Example:
> DELETE /conversations/0fa26937-1c2b-4aef-8556-da0fb3ec882d/bots/d7473851-c0bf-4963-8df4-a0ed7c53d124
< 200 OK
< Content-Type: application/json
<
< {
< "event": {
< "type": "conversation.member-leave",
< "conversation": "0fa26937-1c2b-4aef-8556-da0fb3ec882d",
< "from": "62c2157d-2081-46f0-b8aa-088d7a48142d",
< "time": "2016-08-16T14:49:14.123Z",
< "data": {"user_ids": ["d7473851-c0bf-4963-8df4-a0ed7c53d124"]}
< }
< }
If the bot is not a member of the conversation, a 204 response is returned.
Note: This list of tags is an early draft and subject to change.
The currently available service tags are:
audiobooksbusinessdesigneducationentertainmentfinancefitnessfood-drinkgamesgraphicshealthintegrationlifestylemediamedicalmoviesmusicnewsphotographypollproductivityquizratingshoppingsocialsportstraveltutorialvideoweather