Skip to content

feat(whatsapp): implement native typing indicators via Cloud API - #1173

Open
JuanBifrost wants to merge 1 commit into
ChatbotXIO:mainfrom
JuanBifrost:feat/whatsapp-typing-indicator
Open

JuanBifrost wants to merge 1 commit into
ChatbotXIO:mainfrom
JuanBifrost:feat/whatsapp-typing-indicator

Conversation

@JuanBifrost

Copy link
Copy Markdown
Contributor

Summary

Implements native WhatsApp typing indicators via the WhatsApp Business Cloud API according to Meta's official documentation:
https://developers.facebook.com/documentation/business-messaging/whatsapp/typing-indicators

Context & Problem

Previously, the WhatsApp conversation handler attempted to call markAsRead with a hardcoded "lastMessageId" dummy string and did not implement typing indicator payloads. Additionally, flow steps executing typing did not pause execution to allow the typing indicator to remain visible before sending the subsequent message.

Changes

  1. SDK (packages/sdk):

    • Extended ConversationHandlers["sendTyping"] input type with optional messageId?: string.
  2. Worker Config (packages/worker-config):

    • Added optional messageId?: string to ChatJobSendTyping["data"].
  3. WhatsApp Integration (integrations/whatsapp):

    • Implemented native sendTyping using whatsappClient.$$apiFetch$$ with the official Meta endpoint POST /<API_VERSION>/<PHONE_NUMBER_ID>/messages and payload:
      {
        "messaging_product": "whatsapp",
        "status": "read",
        "message_id": "<INCOMING_MESSAGE_ID>",
        "typing_indicator": {
          "type": "text"
        }
      }
    • Gracefully handles missing messageId and API/network errors without throwing unhandled exceptions.
    • Cleared broken "lastMessageId" dummy call in agentMarkAsRead.
  4. Worker Step Execution (apps/worker):

    • In stepSendTyping, dynamically resolves the latest incoming message ID (sourceId) for the conversation via messageService.findLatestIncomingMessage (following the service -> repository -> DB pattern).
    • Pauses execution via setTimeout for the configured duration (props.step.seconds, clamped between 1s and 60s) so the typing indicator remains visible on the user's phone before subsequent flow messages are dispatched.
    • Forwarded messageId in sendTypingToChannel (with fallback lookup for WhatsApp) and in processAutomatedResponse (triggerMessage?.sourceId).
  5. Unit Tests:

    • Added integrations/whatsapp/__tests__/conversation-typing.test.ts to test typing payloads, missing ID handling, and error resiliency.
    • Added apps/worker/__tests__/step-typing-handler.test.ts to test step delay, message lookup, and channel dispatch.

Verification

  • Tested locally and in production deployment with WhatsApp Cloud API: typing indicator (... escribiendo) renders on device during configured step seconds before response message arrives.
  • Unit tests added and passing for both integration handler and worker step handler.

@github-actions github-actions Bot added the feature New feature or request label Sep 13, 2026
@JuanBifrost
JuanBifrost force-pushed the feat/whatsapp-typing-indicator branch from 560fc5f to 7765640 Compare September 13, 2026 20:12
- Implement native WhatsApp typing indicator per Meta official documentation
- Thread messageId into ConversationHandlers sendTyping and ChatJobSendTyping
- Pass latest incoming message sourceId as message_id to Cloud API messages endpoint
- Enforce configured delay in stepSendTyping so typing indicator remains visible before subsequent steps
- Add unit tests for WhatsApp sendTyping handler and worker stepSendTyping
@JuanBifrost
JuanBifrost force-pushed the feat/whatsapp-typing-indicator branch 3 times, most recently from 85ba534 to dda005d Compare September 13, 2026 23:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

feature New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant