Custom Desk

Custom Desk#

Custom Desk lets you connect an agent inbox you built or run yourself, without waiting for a Gydr connector. Gydr publishes one contract, you implement it, and a business connects the two in the Console. Nothing is built per partner on Gydr's side.

When a visitor needs a person, the bot steps aside and a human agent takes the conversation. That moment is a handoff. Your inbox is where that agent works, and the agent's replies reach the visitor wherever they are: website chat, WhatsApp, Messenger, Instagram or Telegram.

How it works#

It has the shape of the professional desks Gydr connects to (Zendesk, LiveChat, Freshchat): Gydr calls your REST API, and you send signed webhooks to Gydr. One shared secret signs both directions with the same scheme.

• Gydr to you (REST). Gydr calls the endpoints you host under one base URL: open a conversation, post a message, end it, ask whether an agent is online, file a ticket, and a connection test.
• You to Gydr (webhooks). You POST signed events to your integration's Gydr events URL: an agent replied, the agent closed the conversation, handed it back to the bot, or took it over.
• The business connects the two in the Console. It pastes your base URL and a shared signing secret, chooses which options to allow, and gives you the Gydr events URL.

The conversation lifecycle#

1. With mirroring on, Gydr calls POST /sessions/{sessionId}/messages (phase mirror) while the bot answers.
2. The visitor asks for a person. If the business turned the availability check on, Gydr first calls GET /availability.
3. Gydr calls POST /conversations with the transcript. You answer with your conversation ID.
4. Each visitor message arrives as POST /sessions/{sessionId}/messages (phase handoff). Your agent replies with the agent.message event.
5. The conversation ends one of three ways: your agent sends conversation.close (the session ends, or the bot carries on if the business chose that), your agent sends conversation.release (the bot resumes), or Gydr calls POST /sessions/{sessionId}/end (the visitor left or the session timed out).

While a handoff is active the bot never replies. Every visitor message goes to you.

What the business configures in the Console#

In Console → Integrations → Custom Desk the business sets:

After saving, the Console shows the integration's Gydr events URL:

https://integration.api.gydr.ai/custom-desk/integrations/{integrationId}/events

The business gives you that URL together with the signing secret. One base URL, one events URL and one secret identify one integration. A business that connects two inboxes gets two of each. Custom Desk works on every Gydr plan.

When the business saves the integration, Gydr calls your connection test. If it does not answer 200 or 204 after checking the signature, the save fails, so a wrong URL or secret is caught at setup rather than when the first visitor asks for help.

The API Gydr calls (you host it)#

Every path below is relative to the base URL. The operations are grouped by mode, as on Zendesk: a business with only Ticket on is only ever sent POST /tickets (and the connection test); one with only Live Support on is never sent it.

Transport, signature and idempotency#

• Content-Type: application/json on every POST. The two GETs have no body. Gydr never follows a redirect.

Test vector. Secret test_secret_0123456789abcdef0123456789abcdef, timestamp 1760774400, and this exact end-request body:

{"sessionId":"sess_abc123","widgetId":"w_1","reason":"inactivity","hadHandoff":false}

The signature is 33490e3eb515650a251006176a35bab2006af7a8f4b246d453a19f9ddd5f5683.

import { createHmac, timingSafeEqual } from "node:crypto"

export function verifyGydr(rawBody, headers, secret) {
  const ts = headers["x-gydr-timestamp"]
  const sig = headers["x-gydr-signature"] ?? ""
  if (!ts || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false
  // rawBody is "" on Gydr's GET requests.
  const expected = createHmac("sha256", secret)
    .update(ts + "." + (rawBody ?? ""))
    .digest("hex")
  return (
    sig.length === expected.length &&
    timingSafeEqual(Buffer.from(sig), Buffer.from(expected))
  )
}

• Delivery is at least once; de-duplicate on Idempotency-Key. Gydr sends the same key every time it retries the same operation: a conversation open is keyed per handoff (a new handoff in the same session gets a new key), a message per message, a ticket per filing. Store the first answer against the key and return it unchanged to a repeat.
• Stay available during handoffs. If a message in the handoff phase fails, the visitor sees that their message could not be passed on. A handoff your side never answers ends at the business's handoff timeout.
• Answer quickly (timeouts in the table above). Store first, process after.
• Return real status codes. Only the success statuses above count. 401/403 tell Gydr your side refused its credentials, another 4xx that the request was wrong, 429 to slow down, and a 5xx or no answer that you are unavailable.

Conversation context and the signed-in visitor#

Every conversation request carries the same context, with keys left out when unknown:

{
  "sessionId": "sess_mnhaeMbe2z2_1YWCAcne3",
  "widgetId": "6650a1b2c3d4e5f6a7b8c9d0",
  "widgetName": "Acme Support",
  "source": "whatsapp",
  "sourceId": "chv_3kq9XcA1…",
  "visitor": {
    "visitorId": "vis_…",
    "userId": "cust_42",
    "signInSourceId": "idp_7Qm2AbCd",
    "visitorDetails": {
      "name": "Aina R.",
      "email": "aina@example.com",
      "phone": "+60123456789"
    }
  }
}

• There when known: opening a conversation and a mirror-phase message always carry source (and sourceId for a messaging app), plus widgetName and whatever visitor details the visitor has shared. A handoff-phase message and the end requests may leave any of them out.
• Key everything on sessionId. Keep the channel and visitor details from the first request, and never treat a missing field later as a change.
• The signed-in visitor is a link. userId appears only when the business turned on Link signed-in visitors and its own sign-in proved who the visitor is. It is the business's own ID for that customer, and signInSourceId names the sign-in it came from. You must resolve it to your own customer record (create the customer on first sight, then reuse it), exactly as Zendesk matches its external_id. A guest carries no userId. Never treat visitorDetails.email as proof of who someone is.

POST /conversations#

A visitor asked for a person, or the bot decided one is needed. From this moment the bot is silent for this session. The body is the context plus:

Answer 200 or 201 with {"conversationId": "<your id>"}. conversationId is optional; if you leave it out, Gydr uses sessionId. Make this idempotent on Idempotency-Key, never on sessionId: a retry of the same handoff repeats its key and must not open a second conversation, while a new handoff in the same session (your agent closed or released the first and the visitor asked again) arrives with a new key and must open a new conversation.

POST /sessions/{sessionId}/messages#

Addressed by session because a mirrored message arrives before any conversation exists. The body is the context plus:

An empty text with attachments is a real message. Do not reject it.

POST /sessions/{sessionId}/handoff/end#

The handoff ended on Gydr's side but the conversation continues with the bot. Today the only cause is reason: "timeout": your side was silent past the business's handoff timeout. The body is the context, conversationId when known, and reason. Close or archive the conversation in your inbox. Your agent can no longer reply to it; agent.message answers 409 no_active_handoff.

POST /sessions/{sessionId}/end#

The Gydr conversation is over. The body is the context, conversationId when a handoff was in progress, and:

Close the conversation (unless ticketKept), and be idempotent: closing something already closed must succeed quietly. You only receive this for conversations you knew about, meaning ones you held or ones that were mirrored to you. After your own conversation.close, no end request follows.

POST /tickets#

Ticket mode only. A visitor chose to leave a ticket instead of talking to a person now. No conversation is opened and the bot keeps answering: create one ticket in your helpdesk and tell Gydr its ID.

Answer 200 or 201 with {"ticketId": "<your id>", "ticketUrl": "<https link>"}. ticketId is required, 1 to 64 characters from A-Z a-z 0-9 . _ - only, and Gydr shows it to the visitor. Any other id is never stored or shown and counts as a failure, but because you answered with success Gydr treats the ticket as possibly created and will not file another. ticketUrl is optional and kept only when it is an https link (the business sees it, the visitor does not). Make this idempotent on Idempotency-Key: Gydr sends the same key again after a timeout, and a retry must not create a second ticket, so answer it with the same ticketId. A 401, 403 or other 4xx tells Gydr the ticket was not created. A timeout, a 5xx, another 2xx or a success without a valid ticketId tells it the ticket may exist, so it will not file another.

GET /availability?widgetId={widgetId}#

"Is at least one agent online right now?" Asked only when the business turned the availability check on. widgetId is left out when Gydr does not know it.

• Answer 200 {"available": true} or {"available": false}. The value must be a JSON boolean.
• Anything else, including a slow answer (over 3 s), an error, or a non-boolean, counts as offline. The bot then apologises and offers the business's other contact options instead of a handoff.
• Gydr caches your answer for 30 seconds.

GET /connection-test#

Called when the business saves the integration, whatever modes it turned on. Answer 200 or 204 once the signature (over the empty body) verifies.

Ordering, mirroring and privacy#

• Gydr sends one session's requests in the order they happen, but separate calls can still arrive out of order. Use sequence during a handoff, and sentAt otherwise.
• With mirroring on, you receive bot conversations as they happen. Visitors who opted out of conversation history are never mirrored and never carry a userId. You will only hear about them if they ask for a person.
• You receive personal data (names, contact details, message content) so an agent can help. The business is the data controller, so handle it under your agreement with them.

Events you send to Gydr#

Transport and signature#

• POST to the Gydr events URL from the Console with Content-Type: application/json. The body is at most 64 KB.
• Sign exactly as Gydr signs its requests to you: X-Gydr-Signature is the lower-case hex HMAC-SHA256 of {timestamp}.{rawBody} with the signing secret, X-Gydr-Timestamp is Unix seconds, and X-Gydr-Event is the body's event.
• Compute a new timestamp and signature on every retry. Gydr rejects a timestamp more than 300 seconds off.

Test vector. Secret test_secret_0123456789abcdef0123456789abcdef, timestamp 1760774400, and this exact body:

{"eventId":"desk-evt-0001","event":"agent.message","sessionId":"sess_abc123","timestamp":"2025-10-18T08:00:00.000Z","data":{"message":"Hi!","sender":{"name":"Alice"}}}

The signature is 41b77e2f14cd09f422d0568133c398554aa4c884bd3488d991c2399b43a1f707.

import { createHmac } from "node:crypto"

export async function sendToGydr(eventsUrl, secret, event) {
  const body = JSON.stringify(event)
  const ts = String(Math.floor(Date.now() / 1000))
  const sig = createHmac("sha256", secret)
    .update(ts + "." + body)
    .digest("hex")
  return fetch(eventsUrl, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Gydr-Signature": sig,
      "X-Gydr-Timestamp": ts,
      "X-Gydr-Event": event.event,
    },
    body,
  })
}

Envelope, idempotency and errors#

{
  "eventId": "desk-evt-0001",
  "event": "agent.message",
  "sessionId": "sess_abc123",
  "timestamp": "2026-10-18T07:20:00.000Z",
  "data": {}
}

• eventId (required, 1 to 128 characters) is your unique ID for this event. Reuse it when you retry. Gydr returns the original result instead of acting twice. While the first attempt is still running, a retry gets 409 in_progress. Gydr remembers each eventId for 24 hours. An answer in the 5xx range, 409 conflict or 409 in_progress is never remembered, so a retry with the same eventId runs again. Every other answer, success or refusal, is final for that eventId. Every event (a reply, a close, a release, a takeover) is acted on, and charged, at most once per eventId. In the rare case Gydr cannot return the original answer, a retried reply or release answers 200 {"duplicate": true}, a retried close answers 200 {"alreadyEnded": true}, and a retried takeover answers 200 {"status":"agent","ticketId"} while your desk still holds the conversation, otherwise 200 {"duplicate": true}.
• sessionId is the Gydr session from the events you received.

Errors have the shape { "error": { "code": "…", "message": "…" } }. These can come back for any event:

agent.message#

Send an agent reply.

"data": { "message": "Hi Aina, sorry about that! Could you send a photo?", "sender": { "name": "Alice" }, "conversationId": "your-id-123" }

• message: 1 to 10,000 characters of plain text.
• sender.name: shown to the visitor as the agent's name on website chat.
• conversationId (required): your own id for the conversation, the one you answered POST /conversations with (if you answered none, Gydr uses the sessionId, so send that). The reply reaches the visitor only if that conversation is the one now being handled; after a release and a second handoff on the same session, a late reply from the first conversation answers 409 no_active_handoff. Leave it out and the answer is 400 conversation_id_required and nothing is sent; resend with a new eventId.

Gydr does not echo your agent's messages back to you as events.

conversation.close#

Close the conversation.

"data": { "reason": "Resolved: replacement sent", "conversationId": "your-id-123" }

conversationId is required, as on agent.message: without it the answer is 400 conversation_id_required and nothing is closed, and a close that names an earlier conversation is answered 409 no_active_handoff and closes nothing.

By default this ends the Gydr session; under "Let the chatbot carry on" it hands the conversation back instead. With the business's default ("End the conversation"), the visitor is told your team has closed the conversation, and a new message from them starts a fresh conversation. If the business chose "Let the chatbot carry on", your close ends the handoff, the session stays open, the visitor is told they are back with the assistant, and the bot answers their next message. Which applies is fixed when the handoff starts. Either way, the answer is 200 {"status":"handoff_ended"}, or 200 {"alreadyEnded": true} if the conversation was already over (both sides often close at once, and this is safe). If the conversation is still live but no handoff is active (the bot is handling it, or your agent already released it), nothing is closed and the answer is 409 no_active_handoff. No end request follows your own close.

conversation.release#

Hand the conversation back to the bot.

"data": { "reason": "Order question answered" }

The handoff ends, the conversation continues, and the bot answers the visitor's next message. The visitor is told they are back with the assistant. Mirroring, if on, continues. Answers: 200 {"status":"released"}, 403 release_disabled, 409 no_active_handoff (the conversation is live but no handoff is active: already released, or timed out), and 409 session_ended (the conversation was closed or has ended).

conversation.takeover#

Take over a conversation the bot is handling.

"data": { "conversationId": "your-id-123", "agent": { "name": "Alice" } }

Your agent takes a conversation the bot is handling (you know about it from mirrored messages). The bot stops at once, and a reply it was still writing is discarded. In rare cases a reply already being sent at that exact moment may still arrive. The visitor is told they are connected to a person. From here it behaves exactly like a handoff your desk accepted.

Rate limits#

Every plan gets the same limits.

Over a limit you get 429 rate_limited with a Retry-After header in seconds. Wait that long and retry with the same eventId.

Credits#

Everything Gydr sends to your desk is free. Actions your agent takes on a conversation use credits. The amounts live on How Credits Work.

Rules for your agent UI#

• Label agent transcript lines and author: agent messages as a human agent, and assistant transcript lines and author: assistant messages as bot or business, never as a human agent.
• Show source, because "this customer is on WhatsApp" changes how agents write. On messaging channels, warn when a draft is close to the channel's length limit.
• Treat held as "sent, waiting for the customer". It is not a failure.

Go-live checklist#

Test each of these on a Gydr sandbox before going live.

• GET /connection-test verifies the signature over the empty body; a wrong secret gets 401
• The same Idempotency-Key delivered twice produces one record and the same answer
• A /sessions/{sessionId}/… request whose body sessionId differs from the path is refused
• POST /conversations opens one conversation, seeded with the transcript; a second handoff in the same session (new Idempotency-Key) opens a new one
• A signed-in visitor's userId lands on your existing customer record (Link signed-in visitors on); a guest carries none
• Visitor messages during a handoff arrive in sequence order, including attachment-only ones
• An agent reply reaches website chat and WhatsApp; an over-limit reply shows the limit
• A WhatsApp reply after the window closed comes back held
• conversation.close closes and the visitor is told; sending it twice is safe
• conversation.release: the bot answers the next visitor message
• conversation.takeover while the bot is mid-reply: the bot's reply never reaches the visitor
• Your outgoing events are signed (test vector above); a retried event with the same eventId acts once
• A 429 is retried after Retry-After with the same eventId
• POST /tickets creates one ticket and answers { "ticketId" }; the same Idempotency-Key twice returns the same ticket (only if Ticket is turned on)
• POST …/handoff/end (timeout) and POST …/end close the conversation in your inbox; ticketKept: true keeps it open
• GET /availability answers within 3 seconds with a JSON boolean