Skip to content

Ledger entryNo. 348796

Helpdesk Integration

Also called: WhatsApp helpdesk integration · Ticketing integration · WhatsApp to ticket

Definition
Connecting WhatsApp to a ticketing system so inbound messages become tickets and agent replies go back to the customer through the API.

Support & operations

Mode · transformer

Work it out

Mask contact details before they spread into tickets and logs

Masking hides personal data before it reaches logs and dashboards, while keeping enough to recognise it.

Try

Text with email addresses or phone numbers.

Masked for logs and exports
New WhatsApp ticket from +•• ••••• •3210: order 4471 arrived with a cracked door, please call back.
Emails
0
Numbers
1
  • Masked 1 phone or long number.
  • Numbers keep their last 4 digits — enough to confirm with a customer, useless to a fraudster.
  • Masking is one-way: do it before text reaches logs, analytics or exports.
Pick an inbound WhatsApp message as it might land in a ticket comment or export. The masked output keeps the last four digits and the email domain, which is enough for an agent to confirm identity.

What is a helpdesk integration?

A helpdesk integration connects a WhatsApp Business API number to a ticketing or help-desk system so that support teams can work WhatsApp conversations alongside email and web tickets. Inbound messages arrive at your server as webhook events, the integration creates or updates a ticket, and when an agent replies in the helpdesk the integration sends that reply to the customer with a POST to the Cloud API /{PHONE_NUMBER_ID}/messages endpoint.

Most of the work is mapping two different models onto each other. WhatsApp is a continuous chat thread per customer with message statuses (sent, delivered, read, failed); a helpdesk is a set of discrete tickets with statuses such as open, pending and solved. The integration decides when a new message joins an existing ticket, when it opens a new one, how attachments are fetched (media URLs expire after 5 minutes), and how delivery failures are written back to the ticket so agents know a reply never arrived.

It is often confused with a CRM integration. A CRM integration syncs who the customer is — contact fields, deals, consent flags. A helpdesk integration syncs what the customer is asking for and where that request stands in its ticket lifecycle. Many businesses run both, with the CRM as the source of contact data and the helpdesk as the source of support history.

Key takeaways

  • A helpdesk integration turns inbound WhatsApp messages into tickets and sends agent replies back out through the Cloud API.
  • Key the ticket on the customer and an open status, not on each message, or every WhatsApp line becomes a separate ticket.
  • Use the message id (wamid) as an idempotency key, because Meta retries webhook deliveries for up to 7 days.
  • Agent replies are free-form only inside the 24-hour service window; after it closes the helpdesk must send an approved template.
  • It differs from a CRM integration, which syncs customer records; a helpdesk integration syncs conversations and ticket state.

How does a helpdesk integration work?

  1. Receive and verify the webhook

    Subscribe to the messages field, verify the X-Hub-Signature-256 HMAC on the raw body, and acknowledge with HTTP 200 quickly. Do the ticket work in a queue so slow helpdesk APIs never cause webhook retries.

  2. Find or create the ticket

    Look up an open ticket for the sender (messages[0].from, or the business-scoped user ID where the phone number is withheld). If one exists, append the message as a comment; if not, create a ticket with the contact name from contacts[0].profile.name.

  3. Deduplicate on the wamid

    Store each message id and skip any you have seen. Meta retries undelivered webhooks for up to 7 days, so duplicates are normal, not exceptional.

  4. Send agent replies through the API

    When a public reply is added in the helpdesk, post it to /{PHONE_NUMBER_ID}/messages. Inside the 24-hour service window send type: text; outside it, send an approved template. Internal comments must never be forwarded.

  5. Write statuses back

    Map statuses webhooks to the ticket: show delivered and read ticks on the agent's reply, and raise a visible alert on failed with the error code so the agent can retry or switch channel.

In code

A helpdesk integration in code

// Express handler: WhatsApp inbound message -> helpdesk ticket (signature check omitted for brevity).
app.post("/webhooks/whatsapp", express.raw({ type: "application/json" }), async (req, res) => {
  res.sendStatus(200); // acknowledge first; Meta retries non-200 responses
  const body = JSON.parse(req.body.toString("utf8"));
  const value = body.entry?.[0]?.changes?.[0]?.value;
  for (const msg of value?.messages ?? []) {
    if (await seen.has(msg.id)) continue;          // wamid as idempotency key
    await seen.add(msg.id);
    const sender = msg.from_user_id ?? msg.from;        // BSUID first; phone can be withheld for username users
    const name = value.contacts?.[0]?.profile?.name ?? sender;
    const ticket = await helpdesk.findOpenTicket({ externalId: sender })
      ?? await helpdesk.createTicket({ externalId: sender, requester: name, channel: "whatsapp" });
    await helpdesk.addComment(ticket.id, {
      public: true,
      body: msg.type === "text" ? msg.text.body : `[${msg.type} received]`,
      externalMessageId: msg.id,
    });
  }
});

`helpdesk` and `seen` stand in for your ticketing client and a durable dedupe store.

The figures

A helpdesk integration: key facts and limits

Inbound source
messages webhook field
Outbound endpoint
POST /v26.0/{PHONE_NUMBER_ID}/messages
Webhook retries
Up to 7 days on non-200 or failure
Signature header
X-Hub-Signature-256 (HMAC-SHA256)
Media URL lifetime
5 minutes after you fetch it
Text body limit
4,096 characters

Costly mistakes

Common mistakes with a helpdesk integration

  • One ticket per message

    Customers send three short lines where email users send one paragraph. Group messages into the open ticket for that sender and only open a new ticket after the previous one is solved or closed.

  • Forwarding internal comments

    If the integration sends every new comment, a private note can reach the customer. Only forward comments explicitly marked public, and test that path before go-live.

  • Ignoring the service window

    A reply typed two days after the customer's last message fails as free-form text. Show the window state on the ticket and offer approved templates when it has closed.

  • Storing raw media links

    Media URLs from the API expire within minutes. Download the file with your access token and attach the file itself to the ticket.

  • Copying full phone numbers into every log

    Tickets, exports and logs multiply personal data. Mask phone numbers and emails outside the ticket record and limit who can export conversations.

Why does a helpdesk integration matter?

Without an integration, WhatsApp becomes a side channel: agents copy messages into tickets by hand, SLA timers never start, and reporting misses the channel customers use most. Integrating it puts WhatsApp under the same queues, SLAs, macros and reporting as every other channel, while keeping the reply inside the same WhatsApp thread the customer started.

Example: An appliance brand in Pune moves WhatsApp into its ticket queue

A Pune appliance maker receives about 1,200 WhatsApp service requests a day. Its integration groups each customer's messages into one open ticket, downloads photos of damaged products and attaches them, and tags tickets by product from a list message the bot sends first. Agents reply from the helpdesk; the integration sends the text through the Cloud API and writes delivered and read ticks back. When a ticket is pending for more than 24 hours, the reply box offers the approved service_followup template instead of free text. Duplicate tickets fall sharply once wamid deduplication goes live.

Best practices for a helpdesk integration

  • Put the wamid on every ticket comment so a message can be traced end to end.
  • Process webhooks from a queue so a slow helpdesk API never causes Meta to retry.
  • Write failed statuses into the ticket as a visible event, not just a log line.
  • Sync tags both ways so reporting matches across WhatsApp and other channels.

Helpdesk Integration FAQs

Can a helpdesk reply to WhatsApp customers directly?
Yes, through the integration. The helpdesk itself does not talk to WhatsApp; the integration takes the agent's public reply and sends it with the Cloud API messages endpoint, then writes delivery statuses back to the ticket.
What happens when an agent replies after 24 hours?
A free-form reply fails once the 24-hour service window has closed. The integration must send an approved template instead, which reopens the window when the customer responds.
How do I stop duplicate tickets from WhatsApp?
Deduplicate on the message id and group messages by sender. Meta retries webhooks for up to 7 days, and customers send several short messages, so both checks are needed.
Is a helpdesk integration the same as a CRM integration?
No. A CRM integration syncs customer records such as contact details and consent; a helpdesk integration syncs support conversations and ticket statuses. They often run side by side.

See InfiQ pricing

Put Helpdesk Integration to work

InfiQ is an official Meta Business Partner. Start a 7-day free trial — no card needed — and see this running on your own number.

Start free trialBrowse all 550 terms