Adding WhatsApp coordination to field-service software: a vendor integration blueprint

WhatsApp can be the conversation layer, but the vendor's platform must remain authoritative for tenants, jobs, permissions, ownership and outcomes. Adding messaging should not create a second work-order system or allow a convenient group to bypass customer boundaries.

For product managers, technical founders, integration engineers and platform architects at field-service software vendors and vertical SaaS platforms, the difficult part is not sending one message. It is making job-linked conversations configurable, recoverable and accountable across customer organisations. This blueprint describes design requirements to evaluate, not a promise that Jely or any particular messaging connection provides every capability.

1. Define the tenant–job–conversation contract

Start with stable internal identifiers, not group names, phone numbers or site addresses. Names change; a phone number may appear in several customer organisations. Every lookup and action must resolve within an authorised tenant before it touches conversation content.

• Tenant: the customer organisation and its authorised connection/configuration scope.
• Job/work order: the platform's stable reference, current version, site and approved lifecycle state.
• External participant: a tenant-scoped contact reference, verified role and current relationship to the job.
• Conversation: group or one-to-one identifier, connection reference, membership and provisioning state.
• Message: logical action reference, individual attempt references, source event and conversation association.
• Internal team destination: the authorised Slack channel, shared queue or team workspace mapped to the job.
• Owner: the person or role accountable for the next action, with acceptance time and deputy.
• Authoritative outcome: approved decision, target record/version, writer and verified saved result.

Use tenant-scoped keys throughout mappings, queues, caches, media retrieval and exports. Derive tenant context from the authenticated connection and verify its relationship to the job; do not trust a tenant identifier supplied in a request body alone. A shared contact must never imply shared access.

2. Let customers configure approved lifecycle triggers

Offer explicit rules for events such as job accepted, visit scheduled, team assigned, access needed, exception raised and job closed. Each rule needs a permitted action, recipient-selection rule, approved content, operating hours, owner and failure route. Let customers enable only the events their teams can monitor.

Record the job version and configuration version used for each request. Recheck the current job before acting: a visit may have moved or an operative may have been replaced since the event was raised. A trigger requests work; it does not establish successful provisioning, recipient acceptance or delivery.

For example, “visit scheduled” might request an approved customer update, while “exception raised” requests an internal handoff. Neither should change the visit time merely because a recipient suggests another slot in chat.

3. Verify groups and templates separately

Maintain a capability checklist for each chosen provider, connection and configuration. Verify group creation, membership changes, one-to-one messages, template-triggered messaging, event receipt, media retrieval and exports independently. Availability in one setup does not establish availability in another.

Do not assume that a setup supports both group operations and templates, or that templates can automatically be sent into groups. Treat the destination type, recipient permissions, approved message requirements and delivery feedback as separate checks. Where a required action is unsupported, disable it with a clear explanation rather than silently substituting a different audience.

The existing installer-network automation blueprint covers project groups, webhooks and evidence retrieval in more depth. Here, the additional concern is making those boundaries explicit across independently configured customer tenants.

4. Agree vendor and customer responsibilities

A connector cannot decide who monitors a contractor's reply or approves a client report. Document the following allocation, then name accountable people and backups in the customer's operating agreement. Adapt it to the actual service arrangement rather than treating it as a legal allocation.

Make urgent and out-of-hours alternatives explicit. A delivery indicator, staffed queue or moderation rule is not an emergency response service. Privacy arrangements must also reflect the actual setup: ordinary groups can expose participant phone numbers.

5. Make the lifecycle recoverable

Persist a lifecycle for each tenant/job coordination workspace, separate from the job's business status:

• Requested: accepted for evaluation; no conversation or message success is implied.
• Validating: checking current permissions, participants, configuration and supported capabilities.
• Provisioning: creating or linking supported destinations and recording verified identifiers.
• Active: required mappings and monitoring are ready for the approved workflow.
• Degraded: a required connection, destination or reconciliation step is unavailable; affected work remains visible.
• Closing: stopping new triggers, resolving pending work and applying agreed access/retention rules.
• Closed: closure checks are recorded; late events still follow an explicit review policy.

Prevent duplicates without hiding uncertainty

Scope an idempotency key to tenant, job, intended action and relevant business revision. API calls, dashboard actions and recovery tools must consult the same operation register. A retry is another attempt at the same intention, not a new instruction to create another group.

After a timeout, check permitted provider status or mapping evidence before retrying an action with an uncertain result. If the result cannot be verified, leave it pending investigation. Do not label an unknown outcome as either success or safe-to-repeat failure.

Recover events in a controlled order

Verify webhook authentication, validate payloads and acknowledge receipt only according to a documented durable-processing contract. Deduplicate event IDs and use job versions or explicit sequence checks to prevent old events reversing newer decisions. Do not rely on arrival order.

Retry transient errors with back-off, a bounded attempt budget and an expiry. Route permanent failures or exhausted retries to an owned failed-work queue. Replay must recheck permissions, current job state and previous results; retain the original event reference and recovery decision.

Give customers useful diagnostics: affected job, operation, last attempt, failure category, next action and owner. Keep secrets, unnecessary message content and other tenants' identifiers out of these views and diagnostic logs.

6. Require accepted team handoffs

A Slack notification or shared-team alert is not accepted ownership. Carry the tenant/job reference, source link, reported issue, requested action, deadline and current approval boundary into the authorised destination. Require an acknowledgement and named owner; an automated acknowledgement must not impersonate human acceptance.

Start an escalation timer when the handoff is raised. If nobody accepts within the configured monitored-hours rule, notify the deputy or agreed escalation role. Shift changes require explicit transfer rather than assuming the next team has read the channel.

Return the resolved outcome to the originating job through its authorised update process, and send only the approved external response. Keep internal notes separate from outbound content. The WhatsApp, Intercom and Slack support workflow explains shared-team ownership and reply boundaries without making Slack the competing record.

7. Reconcile outcomes, not just delivery events

Track distinct facts: request received → conversation created → message attempted → message sent → reply received → action accepted → authoritative record updated. These are not interchangeable success flags, and not every workflow needs a newly created conversation.

Define what “sent” means in the actual provider response and record delivery feedback separately where available. A successful send does not prove delivery, understanding or approval. Webhook receipt proves neither that an operator accepted the task nor that the work-order change persisted.

Use a single-writer rule for each formal outcome: one authorised update path writes the business decision, whether initiated by a person or a configured integration. Check expected record version, approval and current assignment before writing. Verify the saved result and retain its reference; conflicting, denied or uncertain writes remain owned reconciliation exceptions.

For a proposed visit change, “customer replied” is a conversation fact. “New visit approved and saved against the correct work order” is the operational outcome. Do not close the exception between those two facts. The template delivery metrics and support handoffs guide adds counting and attribution rules so retries and delivery totals do not conceal unresolved work.

8. Design exports and offboarding per tenant

Authorise export requests against tenant, role, job scope and date range. State the time zone and whether filtering uses event time or receipt time. Include stable message/media references, provenance and retrieval status rather than relying on filenames to identify evidence.

Document pagination, snapshot behaviour and completeness limits. A package may omit inaccessible media, deleted content, unsupported event types or information outside connected conversations. List missing items and failed retrievals explicitly; do not describe a partial export as a complete history.

Apply approved retention separately to conversations, mappings, operational logs, media, reports and exports. Review permission at generation and download, restrict expiry and recipients, and record who exported what. Human approval is still needed before issuing a client-facing report based on these materials. An export is not automatically a compliant archive or proof of legal defensibility.

Offboarding should stop scheduled sends, revoke credentials and access, cancel queued retries and settle pending record updates. Agree any permitted final export and retained obligations before deletion. Document what can be deleted and what remains in recipients' devices, external systems, backups or authorised retained records; removal from a group does not erase earlier copies.

9. Test the platform boundary before launch

Use synthetic tenants, jobs and participants, with an authorised test configuration. Require evidence of the expected result, not just a successful HTTP response.

10. A ten-point launch checklist

1. Confirm supported capabilities and documented limits for each connection.
2. Approve the tenant/job identifier contract and test isolation.
3. Version customer rules, recipients and lifecycle triggers.
4. Assign vendor/customer owners, deputies and monitored hours.
5. Verify group provisioning and template workflows independently.
6. Exercise idempotency, event ordering, bounded retries and replay.
7. Test accepted handoffs, escalation and controlled external replies.
8. Prove single-writer reconciliation, including denied and conflicting writes.
9. Review scoped exports, report approval, retention and offboarding.
10. Pilot with one authorised customer configuration; review unresolved work before expanding.

Jely's approach to service operations centres on managed conversations and central coordination: frontline participants can remain in familiar chats while internal teams work with oversight. Evaluate that fit against the capabilities and responsibilities your product actually requires. Keep your platform authoritative, verify any proposed connection and make human ownership visible before increasing automation.