Portal API reference

Called from your server, never from the browser. It is the one portal endpoint that takes a signature, and the signature needs the project's identity secret - the same one the chat widget's userHash is keyed with, found in the dashboard under the widget's Identity settings.

user_hash = hex(hmac_sha256(key=identity_secret, message=external_id))

Hand the returned token to the page you are rendering and send it back in X-Helpwing-Session on every other call here. It reaches exactly one customer's conversations, and it expires - when it does, ask your server for another, because your server is the only party that knows whether that person is still signed in.

There is no unverified mode. The widget can afford one, because a visitor who proves nothing still gets a conversation of their own; here an unproved claim would be a request to read a stranger's support history, so an unsigned or wrongly signed claim is refused outright.

The customer is matched on external_id. A first-time caller whose email matches a customer who has never been identified takes over that record - which is the point: the conversations they had by email before they ever signed in are the history the portal exists to show them. A record already carrying a different external_id is left alone.

Every conversation belonging to the customer this session was minted for, newest activity first - email, chat and portal alike. A support history is one list, and which door a question came in by is the customer's least interesting fact about it.

Paginated like every other list in the API. Spam is left out: a conversation an agent has marked as spam is one nobody is going to answer, and listing it promises a reply that is not coming.

Files a new ticket for the customer this session belongs to, on the project's default inbox, with the project's default assignee and priority - the same routing an inbound email gets. The ticket.created and message.created webhooks fire.

The conversation's source is portal, which is what tells the agent answering it that the customer is reading their replies in the project's own application and not in a mailbox.

metadata is free-form JSON kept on the ticket and shown beside it - what the form asked, the page they were on, the order they were looking at. It comes from the browser, so treat it as a claim: anything that has to be true belongs in the session exchange's metadata instead, which your server signs and which lands on the customer's record.

The transcript the customer is allowed to see - their own messages, agent replies and system entries, never internal notes - plus a cursor to follow it with.

Appends a message, exactly as an inbound email on the same ticket would: the inbox ordering, preview and counters follow it, a resolved conversation reopens when the project enables reopen_on_customer_reply, the timeline records customer_replied, the message.created webhook fires and the assignee is notified.

Unlike the chat widget, reading a conversation here does not suppress the emailed copy of the agent's reply. A chat panel is open or it is not; a portal is a page somebody may have left open in a tab since Tuesday, and a customer who never comes back to it should still hear the answer.

Send a client_message_id if you retry. Repeating one returns the message it already stored instead of storing a second.

The customer's half of the live update feed, over the same cursor the chat widget and the agent inbox use. Send the cursor from the previous response as since; with wait the request is held open until an agent replies or the wait expires.

Long polling rather than server-sent events, for the reason the widget documents: EventSource cannot set a request header, so a stream would have to carry the session token in the query string.