Podium Webchat Handler

Overview

Ingest Podium webchat messages into your production system and operate the webchat layer when it breaks. This is not a setup walkthrough — it is the handler code your integration runs at 11am on a Saturday when a Brisbane customer's webchat lands on the Sydney store's queue, when two simultaneous webchats from the same phone produce two duplicate contact records, when a customer types 1 of a 1-2-3 answer and the session dies before they finish, and when a customer types STOP and the next session five minutes later still tries to SMS them.

The six production failures this skill prevents:

1. Invalid phone formats accepted — Webchat asks for a phone number and a customer types 0412 345 678 (Australian local) or (415) 555-1234 (US local) without E.164 normalization. The handler stores the local form. The later SMS reply attempt fails silently because Podium expects +61412345678 / +14155551234. The agent thinks they replied; the customer never receives anything.
2. Contact auto-creation race produces duplicates — Two webchats arrive within milliseconds from the same phone (customer opens two tabs, or a webhook retry overlaps the first delivery). Both handlers check "does a contact with this phone exist?", both see no, both create — and now the same human is two contact records, with conversation history split across both.
3. Webchat sessions time out mid-conversation — Podium webchat sessions have a server-side expiry (default ~30 min idle). A customer types 1 of a 1-2-3 multiple-choice answer, walks away to grab lunch, comes back to finish, and discovers the agent picked up the conversation in fresh context without the 1 they sent.
4. Attachment size overflows — Podium accepts attachments up to 25MB. Webchat-to-API integrations that don't validate size client-side before upload fail server-side with a 413 — but only after the customer has waited through the upload progress bar. The customer thinks the image was sent; the agent never sees it.
5. Cross-location chat routing is wrong — A Sydney-based store and a Burleigh Heads–based store share the same Podium org. The webchat widget is embedded on a single corporate site and doesn't pass location_uid on the initial message. Every chat lands in the default location's queue regardless of which store the customer was actually browsing.
6. Opt-out propagation lag — A customer types STOP in an SMS thread. The opt-out flag is recorded in the SMS subsystem but not propagated to the webchat subsystem. Five minutes later the customer starts a new webchat session; the integration still tries to send an SMS confirmation reply and trips a compliance violation.

Prerequisites