topic Re: two-way live chat experience not working in APIs & Integrations

two-way live chat experience not working

sumitkawate — Tue, 09 Dec 2025 13:18:38 GMT

Hello HubSpot Team,

I am trying to build a two-way live chat experience from my own custom chatbot (a Java microservice + HTML frontend). The chatbot successfully sends messages to the user, and I am able to receive agent messages from HubSpot Inbox through webhooks.However, I am unable to send visitor → agent messages back into the same thread using the Conversations API.Here is the request I am calling:Endpoint:
POST https://api.hubapi.com/conversations/v3/conversations/threads/10128928655/messages

Request Body:
{
"type": "MESSAGE",
"text": "Hello! This is a test message from my bot.",
"recipients": [
    {
      "actorId": "A-123456"
    }
],
"senderActorId": "V-987654",
"channelId": "1000",
"channelAccountId": "173363"
}Response:
{
"status": "error",
"message": "Multiple errors validating request.",
"errors": [
    {
      "subCategory": "ConversationsApiError.UNSUPPORTED_ACTOR_TYPE",
      "message": "Actor type VISITOR is not supported for sending"
    },
    {
      "subCategory": "ConversationsApiError.INVALID_ARGUMENT_TYPE",
      "message": "Invalid actorId type"
    },
    {
      "subCategory": "ConversationsApiError.UNSUPPORTED_ACTOR_TYPE",
      "message": "Actor type AGENT is not supported for receiving"
    }
]
}My Use Case

A user is chatting with our AI chatbot (custom-built).
If the user asks for additional help, I collect name, email, phone, and create/update a HubSpot contact.
I then want to hand off the conversation to a live HubSpot agent.
I need two-way messaging between:
- User (from my portal/chatbot)
- Live agent (HubSpot Inbox)

Agent → user works correctly via webhooks.
But visitor → agent fails because the API does not seem to accept VISITOR as a sender actor.What is the correct actor type and configuration to allow messages originating from my external chatbot to be sent into an existing HubSpot conversation thread?
I want to know whether:

I must use a Custom Channel App actor (APP-xxx)?
HubSpot supports simulating a visitor message via API?
Or if there is any supported way to send end-user messages into HubSpot Inbox threads?

Any guidance or best practices would be really appreciated.Please help?

Re: two-way live chat experience not working

SamTassey — Tue, 09 Dec 2025 14:13:00 GMT

Hi @sumitkawate,

Welcome to the HubSpot Community!

I see that you're having trouble sending replies to existing threads using API. I found this existing post in our Community that you may find helpful!

https://community.hubspot.com/t5/APIs-Integrations/Can-t-send-a-message-back-to-the-user-on-Conversations-API/m-p/1133723

I'd also like to tag in some of our Top Contributors to see if they have any tips and tricks on this.

@TomM2, @SteveHTM, @GRajput, @RubenBurdin

-- Do you have any suggestions for @sumitkawate?

Thank you!

Sam, Community Manager

Re: two-way live chat experience not working

sumitkawate — Tue, 09 Dec 2025 14:42:32 GMT

Hi Sam,

Thank you for your reply.

Below one doesn't work as it is Vistor to Agent while the Agent to Vistor works .
{
"type": "MESSAGE",
"text": "Hello! This is a test message from my bot.",
"recipients": [
    {
      "actorId": "A-123456"
    }
],
"senderActorId": "V-987654",
"channelId": "1000",
"channelAccountId": "173363"
}

Any help and solutions?

Re: two-way live chat experience not working

RubenBurdin — Mon, 15 Dec 2025 15:31:33 GMT

Hi @sumitkawate , I’ve bumped into this exact wall. The error you’re getting is basically HubSpot telling you: the Conversations “public messages” endpoint is not meant to impersonate a website visitor. In that API, VISITOR actors aren’t allowed as senders, and AGENT actors aren’t valid as “recipients” in the way you’re modeling it, because that endpoint is oriented around sending messages through an existing channel with supported actor roles.

For your use case (external chatbot UI that can escalate to agents in the HubSpot Inbox), the supported pattern is to implement a Custom Channel, and then post messages as INCOMING/OUTGOING over that channel. That’s the product that’s designed to bridge an external messaging surface into the inbox while keeping a single thread for the agent. Start with the Custom Channels API guide here: https://developers.hubspot.com/docs/api-reference/conversations-custom-channels-v3/guide

Once the channel is registered and connected, your “visitor -> agent” message should be sent as an incoming external message on the custom channel, not as a VISITOR actor on the public thread endpoint. The endpoint you’ll end up using is the Custom Channels “Publish a message” route (it supports messageDirection and delivery identifiers): https://developers.hubspot.com/docs/api-reference/conversations-custom-channels-v3/external-messages/post-conversations-v3-custom-channels-channelId-messages

One quick clarifying question: are you trying to keep using HubSpot’s native Live Chat channel, or are you OK with the inbox showing your integration as its own channel (your custom chatbot) for the agent handoff? That answer determines whether you can stay fully supported.