Annotation - Create or Update - Laburen Documentacion

curl --location --request POST 'https://dashboard.laburen.com/api/annotations' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_KEY>' \
--data-raw '{
    "messageId": "clxxxxxxxxxxxxxxxxx",
    "sentiment": "bad",
    "comment": "The agent provided incorrect information about pricing",
    "tagIds": ["clxxxxxxxxxxxxxxxxx"]
}'

curl --location --request POST 'https://dashboard.laburen.com/api/annotations' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_KEY>' \
--data-raw '{
    "messageId": "clxxxxxxxxxxxxxxxxx",
    "sentiment": "good",
    "comment": "Updated: Actually, the response was correct after clarification",
    "tagIds": ["clxxxxxxxxxxxxxxxxx", "clxxxxxxxxxxxxxxxxx"]
}'

curl --location --request POST 'https://dashboard.laburen.com/api/annotations' \
--header 'Content-Type: application/json' \
--data-raw '{
    "messageId": "clxxxxxxxxxxxxxxxxx",
    "sentiment": "good",
    "comment": "Great response!"
}'

const apiUrl = 'https://dashboard.laburen.com/api';
const apiKey = '<API_KEY>';

const response = await fetch(`${apiUrl}/annotations`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${apiKey}`,
  },
  body: JSON.stringify({
    messageId: 'clxxxxxxxxxxxxxxxxx',
    sentiment: 'bad',
    comment: 'The agent provided incorrect information about pricing',
    tagIds: ['clxxxxxxxxxxxxxxxxx'],
  }),
});

const data = await response.json();
console.log(data);

import requests

api_url = "https://dashboard.laburen.com/api"
api_key = "<API_KEY>"

response = requests.post(
    f"{api_url}/annotations",
    headers={
        "Content-Type": "application/json",
        "Authorization": f"Bearer {api_key}",
    },
    json={
        "messageId": "clxxxxxxxxxxxxxxxxx",
        "sentiment": "bad",
        "comment": "The agent provided incorrect information about pricing",
        "tagIds": ["clxxxxxxxxxxxxxxxxx"],
    },
)

data = response.json()
print(data)

{
  "id": "clxxxxxxxxxxxxxxxxx",
  "messageId": "clxxxxxxxxxxxxxxxxx",
  "conversationId": "clxxxxxxxxxxxxxxxxx",
  "agentId": "clxxxxxxxxxxxxxxxxx",
  "organizationId": "clxxxxxxxxxxxxxxxxx",
  "comment": "The agent provided incorrect information about pricing",
  "sentiment": "bad",
  "status": "pending",
  "createdById": "clxxxxxxxxxxxxxxxxx",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z",
  "tags": [
    {
      "tag": {
        "id": "clxxxxxxxxxxxxxxxxx",
        "name": "bug"
      }
    }
  ]
}

POST

api

annotations

curl --location --request POST 'https://dashboard.laburen.com/api/annotations' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_KEY>' \
--data-raw '{
    "messageId": "clxxxxxxxxxxxxxxxxx",
    "sentiment": "bad",
    "comment": "The agent provided incorrect information about pricing",
    "tagIds": ["clxxxxxxxxxxxxxxxxx"]
}'

curl --location --request POST 'https://dashboard.laburen.com/api/annotations' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_KEY>' \
--data-raw '{
    "messageId": "clxxxxxxxxxxxxxxxxx",
    "sentiment": "good",
    "comment": "Updated: Actually, the response was correct after clarification",
    "tagIds": ["clxxxxxxxxxxxxxxxxx", "clxxxxxxxxxxxxxxxxx"]
}'

curl --location --request POST 'https://dashboard.laburen.com/api/annotations' \
--header 'Content-Type: application/json' \
--data-raw '{
    "messageId": "clxxxxxxxxxxxxxxxxx",
    "sentiment": "good",
    "comment": "Great response!"
}'

const apiUrl = 'https://dashboard.laburen.com/api';
const apiKey = '<API_KEY>';

const response = await fetch(`${apiUrl}/annotations`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${apiKey}`,
  },
  body: JSON.stringify({
    messageId: 'clxxxxxxxxxxxxxxxxx',
    sentiment: 'bad',
    comment: 'The agent provided incorrect information about pricing',
    tagIds: ['clxxxxxxxxxxxxxxxxx'],
  }),
});

const data = await response.json();
console.log(data);

import requests

api_url = "https://dashboard.laburen.com/api"
api_key = "<API_KEY>"

response = requests.post(
    f"{api_url}/annotations",
    headers={
        "Content-Type": "application/json",
        "Authorization": f"Bearer {api_key}",
    },
    json={
        "messageId": "clxxxxxxxxxxxxxxxxx",
        "sentiment": "bad",
        "comment": "The agent provided incorrect information about pricing",
        "tagIds": ["clxxxxxxxxxxxxxxxxx"],
    },
)

data = response.json()
print(data)

{
  "id": "clxxxxxxxxxxxxxxxxx",
  "messageId": "clxxxxxxxxxxxxxxxxx",
  "conversationId": "clxxxxxxxxxxxxxxxxx",
  "agentId": "clxxxxxxxxxxxxxxxxx",
  "organizationId": "clxxxxxxxxxxxxxxxxx",
  "comment": "The agent provided incorrect information about pricing",
  "sentiment": "bad",
  "status": "pending",
  "createdById": "clxxxxxxxxxxxxxxxxx",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z",
  "tags": [
    {
      "tag": {
        "id": "clxxxxxxxxxxxxxxxxx",
        "name": "bug"
      }
    }
  ]
}

This endpoint creates a new annotation or updates an existing one for a message. It supports:

Creating annotations for agent messages
Updating existing annotations (upsert by messageId)
Associating tags with annotations
Public agent access (no authentication required for public agents)
Automatic organization and agent resolution from message

Authentication is optional for public agents. If the message belongs to a public agent, you can create annotations without authentication. Otherwise, authentication is required.

Only agent messages can be annotated. Attempting to annotate a user or contact message will result in a 400 error.

Body

Required

string

required

The ID of the message to annotate (CUID format). The message must be from an agent (not a user or contact).

string

required

Sentiment of the annotation. Valid values: good, bad.

string

required

Comment or feedback text for the annotation. Cannot be empty or whitespace-only.

Optional

array

Array of tag IDs (CUID format) to associate with the annotation. If provided, replaces any existing tags. If omitted or empty, removes all tags.

Response

string

Unique identifier of the annotation (CUID format).

string

ID of the message this annotation refers to.

string

ID of the conversation this annotation belongs to.

string

ID of the agent associated with this annotation.

string

ID of the organization the annotation belongs to.

string

Comment or feedback text for the annotation.

string

Sentiment of the annotation (e.g., good, bad).

string

Current status of the annotation.

string

ID of the user who created or last updated the annotation.

string

ISO 8601 timestamp of when the annotation was created.

string

ISO 8601 timestamp of when the annotation was last updated.

array

Tags associated with the annotation.

Show Tags array items

object

Tag information.

Show Tag object

string

Tag ID.

string

Tag name.

Error Responses

Status Code	Type	Description
400	Bad Request	Comment is empty or whitespace-only, or attempting to annotate a non-agent message.
401	UNAUTHORIZED	Missing or invalid authentication session, and the message does not belong to a public agent, or the message’s organization does not match your session.
404	NOT_FOUND	Message with the specified ID does not exist.
400	INVALID_REQUEST	Message does not have an associated agent ID.

curl --location --request POST 'https://dashboard.laburen.com/api/annotations' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_KEY>' \
--data-raw '{
    "messageId": "clxxxxxxxxxxxxxxxxx",
    "sentiment": "bad",
    "comment": "The agent provided incorrect information about pricing",
    "tagIds": ["clxxxxxxxxxxxxxxxxx"]
}'

curl --location --request POST 'https://dashboard.laburen.com/api/annotations' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_KEY>' \
--data-raw '{
    "messageId": "clxxxxxxxxxxxxxxxxx",
    "sentiment": "good",
    "comment": "Updated: Actually, the response was correct after clarification",
    "tagIds": ["clxxxxxxxxxxxxxxxxx", "clxxxxxxxxxxxxxxxxx"]
}'

curl --location --request POST 'https://dashboard.laburen.com/api/annotations' \
--header 'Content-Type: application/json' \
--data-raw '{
    "messageId": "clxxxxxxxxxxxxxxxxx",
    "sentiment": "good",
    "comment": "Great response!"
}'

const apiUrl = 'https://dashboard.laburen.com/api';
const apiKey = '<API_KEY>';

const response = await fetch(`${apiUrl}/annotations`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${apiKey}`,
  },
  body: JSON.stringify({
    messageId: 'clxxxxxxxxxxxxxxxxx',
    sentiment: 'bad',
    comment: 'The agent provided incorrect information about pricing',
    tagIds: ['clxxxxxxxxxxxxxxxxx'],
  }),
});

const data = await response.json();
console.log(data);

import requests

api_url = "https://dashboard.laburen.com/api"
api_key = "<API_KEY>"

response = requests.post(
    f"{api_url}/annotations",
    headers={
        "Content-Type": "application/json",
        "Authorization": f"Bearer {api_key}",
    },
    json={
        "messageId": "clxxxxxxxxxxxxxxxxx",
        "sentiment": "bad",
        "comment": "The agent provided incorrect information about pricing",
        "tagIds": ["clxxxxxxxxxxxxxxxxx"],
    },
)

data = response.json()
print(data)

{
  "id": "clxxxxxxxxxxxxxxxxx",
  "messageId": "clxxxxxxxxxxxxxxxxx",
  "conversationId": "clxxxxxxxxxxxxxxxxx",
  "agentId": "clxxxxxxxxxxxxxxxxx",
  "organizationId": "clxxxxxxxxxxxxxxxxx",
  "comment": "The agent provided incorrect information about pricing",
  "sentiment": "bad",
  "status": "pending",
  "createdById": "clxxxxxxxxxxxxxxxxx",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z",
  "tags": [
    {
      "tag": {
        "id": "clxxxxxxxxxxxxxxxxx",
        "name": "bug"
      }
    }
  ]
}

laburen API

Endpoints

Annotation - Create or Update

Body

Required

Optional

Response

Error Responses

​Body

​Required

​Optional

​Response

​Error Responses

Body

Required

Optional

Response

Error Responses