Tag management

Tags classify your conversations so you can segment, report on, and route them. This page describes the recommended flow to manage them through the API: first you retrieve the company’s tag catalog, then you check the tags associated with a conversation, and finally you assign or update them.

Retrieve the company's available tags

Get the catalog with the id of each tag.

Check the conversation's current tags

Review which tags the conversation already has before modifying them.

Assign or update the tags

Send the complete list of id values the conversation should end up with.

Authentication

Every endpoint on this page belongs to the https://api.jelou.ai domain and uses basic authentication.

Field	Location	Type	Required	Description
Authorization	Header	string	Yes	`clientId:clientSecret` credentials encoded in Base64.
Content-Type	Header	string	Yes	`application/json` on requests with a body.

See Introduction to learn how to build the Authorization: Basic header.

How the `roomId` is built

The roomId identifies the conversation between a channel and an end user. It is not a random value: it is built by joining the G prefix, the channel’s botId, and the end user’s id with colons.

G:{botId}:{userId}

Segment	Type	Description
G	string	Fixed prefix. Always uppercase.
botId	string	Unique identifier of the channel where the conversation happens.
userId	string	Unique identifier of the end user within Jelou.

Example

For channel 1234 and user 987654, the roomId is:

G:1234:987654

You can get both values from Get a conversation: the botId in data.Bot.id and the userId in data.User.id.

Do not add spaces or extra characters between segments. A malformed roomId returns 404 Not Found.

1. Retrieve the company’s available tags

Returns the catalog of tags available to a company. Use this endpoint to find the id values you need when assigning tags.

Endpoint

GET https://api.jelou.ai/v1/company/{companyId}/tags

Path parameters

Field	Location	Type	Required	Description
companyId	Path	string	Yes	Unique identifier of the company.

Query parameters

Field	Location	Type	Required	Description
name	Query	string	No	Filters tags by name.
language	Query	string	No	Language of the tag name.
teams	Query	string[]	No	Filters by teams.
bots	Query	string[]	No	Filters by channels.
isGlobal	Query	boolean	No	Includes global tags.
isVisible	Query	boolean	No	Includes only visible tags.
shouldPaginate	Query	boolean	No	Returns paginated results.
limit	Query	number	No	Maximum number of records per page.

Request example

curl --request GET \
  --url 'https://api.jelou.ai/v1/company/COMPANY_ID/tags?isVisible=true&limit=50' \
  --header 'Authorization: Basic {{Base64EncodedClientId:ClientSecret}}'

Response example

{
  "data": [
    {
      "id": 11,
      "name": {
        "es": "VIP",
        "en": "VIP"
      },
      "color": "#aabbcc",
      "isVisible": true,
      "isGlobal": false
    }
  ]
}

Response details

Field	Type	Description
id	integer	Tag identifier. This is the value you send when assigning tags.
name	object	Tag name per language (`es`, `en`, and so on).
color	string	Tag color in hexadecimal format.
isVisible	boolean	Whether the tag is shown in the platform.
isGlobal	boolean	Whether the tag is available across the whole company.

2. Get a conversation’s information

Returns the full information of a conversation, including the tags currently associated with it.

Endpoint

GET https://api.jelou.ai/v1/rooms/{roomId}

Path parameters

Field	Location	Type	Required	Description
roomId	Path	string	Yes	Unique identifier of the conversation, in the `G:{botId}:{userId}` format.

Query parameters

Field	Location	Type	Required	Description
addConversation	Query	boolean	No	Includes additional conversation information.

Request example

curl --request GET \
  --url 'https://api.jelou.ai/v1/rooms/ROOM_ID' \
  --header 'Authorization: Basic {{Base64EncodedClientId:ClientSecret}}'

Response example

{
  "data": {
    "id": "G:1234:987654",
    "name": "John Doe",
    "channel": "whatsapp",
    "tags": [
      {
        "id": 14,
        "name": {
          "es": "Cliente VIP"
        }
      },
      {
        "id": 15,
        "name": {
          "es": "Cliente Frecuente"
        }
      }
    ]
  }
}

The tags assigned to a conversation are read from the data.tags attribute.

3. Assign or update a conversation’s tags

Assigns or updates the tags of a conversation.

Endpoint

POST https://api.jelou.ai/v1/bots/{botId}/rooms/tags

Path parameters

Field	Location	Type	Required	Description
botId	Path	string	Yes	Unique identifier of the channel the conversation belongs to.

Body parameters

Field	Location	Type	Required	Description
roomId	Body	string	Yes	Identifier of the conversation, in the `G:{botId}:{userId}` format.
tags	Body	integer[]	Yes	List of tag `id` values to associate.

Request example

curl --request POST \
  --url 'https://api.jelou.ai/v1/bots/BOT_ID/rooms/tags' \
  --header 'Authorization: Basic {{Base64EncodedClientId:ClientSecret}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "roomId": "G:1234:987654",
    "tags": [1, 2]
  }'

Response example

{
  "data": {
    "id": "G:1234:987654",
    "tags": [1, 2]
  },
  "message": "Tags assigned successfully."
}

Considerations

The array sent in tags fully replaces the conversation’s current tags. It does not add tags to the existing ones.

Every tag you send must exist and be available to the specified channel.
To keep the already assigned tags and add new ones, send both the existing and the new tags in the array.
If you send an empty array ([]), all tags associated with the conversation are removed.

Example

Say the conversation currently has the tags [14, 15]. To add tag 20 and keep the existing ones, send all three:

{
  "roomId": "G:1234:987654",
  "tags": [14, 15, 20]
}

If you send only the new tag, tags 14 and 15 are replaced and the conversation keeps tag 20 alone:

{
  "roomId": "G:1234:987654",
  "tags": [20]
}

Response codes

Code	Status	Description
200	OK	Successful operation.
400	Bad Request	Invalid request.
401	Unauthorized	Not authorized.
404	Not Found	Resource not found.
500	Internal Server Error	Internal server error.

API reference

Send Messages

Campaigns

Conversations

Tags

Metrics

Users

Resources

Widget

Datum

External Support Panel

Custom Channel

Memory Management

Authentication

How the `roomId` is built

Example

1. Retrieve the company’s available tags

Endpoint

Path parameters

Query parameters

Request example

Response example

Response details

2. Get a conversation’s information

Endpoint

Path parameters

Query parameters

Request example

Response example

3. Assign or update a conversation’s tags

Endpoint

Path parameters

Body parameters

Request example

Response example

Considerations

Example

Response codes

​Authentication

​How the roomId is built

​Example

​1. Retrieve the company’s available tags

​Endpoint

​Path parameters

​Query parameters

​Request example

​Response example

​Response details

​2. Get a conversation’s information

​Endpoint

​Path parameters

​Query parameters

​Request example

​Response example

​3. Assign or update a conversation’s tags

​Endpoint

​Path parameters

​Body parameters

​Request example

​Response example

​Considerations

​Example

​Response codes

Authentication

How the `roomId` is built

Example

1. Retrieve the company’s available tags

Endpoint

Path parameters

Query parameters

Request example

Response example

Response details

2. Get a conversation’s information

Endpoint

Path parameters

Query parameters

Request example

Response example

3. Assign or update a conversation’s tags

Endpoint

Path parameters

Body parameters

Request example

Response example

Considerations

Example

Response codes