In BoldDesk, the Messages API is designed to return message‑level data efficiently and securely. To achieve this, the API includes only a reference identifier—userId or visitorId—in the author object, instead of returning full Contact or Visitor profile details.

This article explains how author identification works in BoldDesk, why the Messages API behaves this way, and how to retrieve complete Contact or Visitor information using the appropriate BoldDesk Developer API endpoints.

Use Cases

This article is useful when you need to:

• Display sender names outside the Agent Portal
• Correlate messages with Contacts or Visitors
• Build integrations using BoldDesk Developer APIs
• Process high‑volume message data efficiently
• Follow BoldDesk’s recommended API usage patterns

How Author Identification Works in the Messages API

The Messages API returns conversation messages along with an author object that identifies who sent each message.
Depending on the sender type, the API includes:

• userId – When the message is sent by a Contact
• visitorId – When the message is sent by a Visitor

The Messages API intentionally excludes full profile details such as name, email address, or phone number.

Why the Messages API Returns Only IDs

BoldDesk follows a separation‑of‑concerns API design, where each API is responsible for a specific data domain.
Key reasons for returning only identifiers include:

• Performance optimization – Prevents repetitive profile data in every message payload
• Data consistency – Ensures Contact and Visitor data is retrieved from a single authoritative source
• Security and privacy – Limits exposure of personal information
• Scalability – Supports efficient retrieval of large message volumes

To access complete profile information, BoldDesk provides dedicated APIs for Contacts and Visitors.

Retrieve Full Contact Details Using the Contacts API

When the Messages API returns a userId, it refers to a Contact in BoldDesk.

Supported Endpoint

GET /contacts/{userId} 

When to Use This Endpoint

• The message is authored by an authenticated customer
• You need the Contact’s name or profile details
• You are linking messages to ticket or contact data

This endpoint returns the full Contact profile associated with the provided userId.

Retrieve Full Visitor Details Using the Visitors API

When the Messages API returns a visitorId, it refers to a Visitor in BoldDesk.

Supported Endpoint

GET /visitors/{visitorId} 

When to Use This Endpoint

• The message is authored by an anonymous or pre‑login user
• You need Visitor information for chat analysis
• The conversation originated from Live Chat before authentication

This endpoint returns the Visitor details associated with the provided visitorId.

FAQs

1. Why doesn’t the Messages API return the author’s name?
   To keep message responses lightweight and secure. Full details are retrieved through dedicated APIs.

2. How do I know whether to use the Contacts API or Visitors API?
   Check the author object:

   • userId → Use Contacts API
   • visitorId → Use Visitors API

3. Can I configure the Messages API to return full author details?
   No. This behavior is fixed and cannot be modified.

4. Does this behavior apply to both ticket and chat messages?
   Yes. The Messages API follows the same author identification pattern across channels.

Related Articles

1. BoldDesk REST API Overview for Developers
2. Generate and Manage API Keys in BoldDesk
3. How to Use Swagger UI to Test the BoldDesk REST API