Context Links

Context Links are links in the conversation sidebar that open external URLs with contact and conversation details filled in. Agents click them to jump to CRMs, billing systems, or internal dashboards without copy-pasting identifiers.

Configuration

Go to Admin → Integrations → Context links and click New context link.

Field	Notes
Name	The link text agents see in the sidebar.
URL template	The URL to open, with the variables below.
Secret	32 characters. Needed only for `{{token}}`.
Token expiry (seconds)	How long `{{token}}` is valid.
Active	Only active links appear in the sidebar.

URL template variables

These placeholders are replaced with the current contact’s details when an agent clicks the link.

Variable	Description
`{{email}}`	Contact’s email
`{{phone}}`	Contact’s phone number
`{{phone_country_code}}`	Contact’s phone country code
`{{external_user_id}}`	Contact’s external user ID
`{{contact_id}}`	Contact’s internal libredesk ID
`{{first_name}}`	Contact’s first name
`{{last_name}}`	Contact’s last name
`{{conversation_uuid}}`	UUID of the current conversation
`{{token}}`	Encrypted token containing all fields (requires secret)

All values except {{contact_id}} and {{conversation_uuid}} are URL-encoded automatically.

Examples

Simple lookup by email:

https://crm.example.com/contacts?email={{email}}

Multiple parameters:

https://billing.example.com/customer?ext_id={{external_user_id}}&email={{email}}

Internal dashboard with conversation context:

https://dashboard.internal/lookup?contact={{contact_id}}&conv={{conversation_uuid}}

Encrypted token:

https://api.example.com/auth/libredesk?token={{token}}

The receiving system decrypts the token to get all contact and agent fields in one payload, without exposing them in the URL.

Encrypted token

When you use {{token}}, libredesk generates an AES-256-GCM encrypted, time-limited token containing all the above fields plus agent_id, agent_email, iat, and exp. The receiving system decrypts it with the shared secret. The token is base64 of a 12-byte nonce followed by the ciphertext. The secret is the AES-256 key. Decrypted, it looks like this:

{
  "email": "user@example.com",
  "phone": "",
  "phone_country_code": "",
  "external_user_id": "",
  "contact_id": 456,
  "first_name": "John",
  "last_name": "Doe",
  "conversation_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "agent_id": 789,
  "agent_email": "agent@example.com",
  "iat": 1750000000,
  "exp": 1750001200
}

Decrypting the token

import base64, json, time
from cryptography.hazmat.primitives.ciphers.aead import AESGCM

def decrypt_context_token(token, secret):
    raw = base64.b64decode(token)
    nonce = raw[:12]
    ciphertext = raw[12:]

    aesgcm = AESGCM(secret.encode('utf-8'))
    plaintext = aesgcm.decrypt(nonce, ciphertext, None)
    return json.loads(plaintext)

# Usage
secret = "your-32-character-shared-secret!"  # exactly 32 characters
payload = decrypt_context_token(token_from_url, secret)

if payload["exp"] < time.time():
    raise ValueError("Token has expired")

print(payload["email"], payload["conversation_uuid"])

Introduction

Getting Started

Configuration

Roles

Contributing

Configuration

URL template variables

Examples

Encrypted token

Decrypting the token

​Configuration

​URL template variables

​Examples

​Encrypted token

​Decrypting the token

Configuration

URL template variables

Examples

Encrypted token

Decrypting the token