Webhooks

Call Received

Triggered when an incoming Voice or Video call is detected.

Best practices

  • Create a 'Missed Call' notification for your agents.

  • Detect if users are calling so your bot can tell them to send a text message instead.

The Voice-to-Text Bridge: Mastering Call Received Webhooks

In a digital-first support ecosystem, the incoming call is often a signal of high urgency or user frustration. While the Wawp platform is primarily an asynchronous messaging engine and does not support the ingestion of raw VoIP audio streams, the [call.received] webhook is a critical diagnostic and operational event. It allows your infrastructure to "Hear" the incoming ringing state, providing your system with the metadata required to bridge the gap between a voice request and a text-based resolution.

This guide provides an architectural deep-dive into the strategic value of call monitoring, moving beyond "Notification" into the realm of Automated Redirection and High-Urgency Triage.

🏗️ Architectural Philosophy: The Call as an Escalation Signal

To master the Call Received API, one must recognize that a WhatsApp call (identified by the [from] JID, usually @c.us) is a "Request for Synchronous Interaction." In the context of a bot-led flow, this is often a signal that the user is finding the text-based menu insufficient for their current needs.

1. The Metadata of the Attempt

The [call.received] event provides the core identifiers of the interaction:

  • The Identity (from): The [@c.us] JID of the caller. This allows for instant CRM lookup.
  • The Vector (isVideo): Distinguishing between an Audio and Video call. A video call attempt often indicates a desire to "Show" a problem (e.g., a broken product) rather than just "Tell" it.
  • The Session (me): Which of your many WhatsApp instances is receiving the call.

2. The Operational Boundary

It is architecturally vital to communicate to your stakeholders that Wawp acts as a Sensor, not a Receiver. Your system cannot "Answer" the call or "Record" the audio. Instead, your system should treat the call event as a Trigger for an Automated Fallback Workflow.

🚀 Strategic Use Cases: Powering Automated Call Failovers

Call monitoring allows you to build a sophisticated "Safety Net" that ensures no customer is left in the "Ringing" void.

1. The "Call-to-Chat" Redirection Strategy

The most powerful use of this webhook is the Instant Redirect. The Strategic Workflow: As soon as the [call.received] event fires, your bot can immediately send a private message to the caller: "Hi there! We saw you trying to call. We currently only offer support via chat to ensure we can handle all requests efficiently. How can I help you today?" Strategic Value: This moves the user from a frustrated "No Answer" state to an active "Chat Ingestion" state within seconds. It manages expectations and keeps the conversation within your manageable support pipeline.

2. High-Urgency Agent Alerting

For premium or VIP accounts, an incoming call should bypass the standard bot and trigger an internal alert for a human agent. The Logic: When the webhook fires for a VIP JID, your system can trigger a desktop notification or a Slack alert: "VIP Customer [Name] is currently calling the WhatsApp line! Please reach out to them via chat immediately." Even if the agent doesn't answer the call (which they can't via API), they can initiate a proactive chat while the user still has their phone in their hand.

3. Calculating the "Frustration Quotient"

By logging the frequency of incoming calls for a specific [chatId], you can calculate an "Engagement Stress" metric. A user who calls 5 times in 10 minutes is in a high-stress state. Your system can detect this pattern and automatically escalate the next text message from that user to a "Priority 1" status, ensuring they receive the fastest possible human response.

🛡️ Administrative Mandate: Scaling the Notification Layer

1. The "Ghost Call" and Bot Loops

Avoid sending a "Why are you calling?" message for every single ring event. WhatsApp sometimes emits multiple events for a single long-ringing session. The Strategy: Implement a Call Debounce. If you receive a call event for User A, do not trigger your "Redirect Bot" again for the same user within the next 2 minutes. This prevented your system from spamming the user with multiple redirect messages for a single call attempt.

2. Respecting the "No-Voice" Perimeter

Clearly state in your business profile and your "Welcome" messages that you do not support voice calls. Use the [call.received] webhook only as a Secondary Defense. The primary defense is setting the right expectations in your text-based UI. If a user calls despite the warnings, your system should respond with firm but polite redirection logic.

🛡️ Operational Best Practices: Designing for Missed Connections

  • Differentiating Between Ringing and Missed: Ensure you coordinate this event with the Call Rejected event. A [call.received] without a rejection often means the call timed out. You should treat "Missed Calls" differently than "Rejected Calls" in your CRM logging.
  • Syncing with Physical Devices: If you have a physical phone linked to the Wawp instance, that phone will ring. This webhook allows your digital backend to "Know" what the human holding that phone is seeing, enabling a unified view of the customer across digital and physical touchpoints.
  • VCard and Identity Correlation: If the caller is not in your CRM, use the [from] JID to initiate a Contact Lookup. You can often retrieve the user's "Push Name" or "About" info even if they just called for the first time, allowing your "Redirect Message" to be personalized (e.g., "Hi John, we saw you calling...").

⚙️ Engineering Best Practices: The Validation Loop

  1. Low-Latency Routing: Call events are time-sensitive. If your redirect message arrives 5 minutes after the call ended, it looks unprofessional. Your handler should aim for sub-500ms processing.
  2. Verify the Session Scope: In a multi-instance environment, ensure the [session] ID is used to filter the redirection logic. You don't want Instance A sending a "We don't support calls" message to a user who called Instance B.
  3. Coordinate with Revocations: Calls do not have "Revocations" in the same way messages do, but they do have "Timeouts." Your system should automatically clear any "Active Call" flag in your dashboard after 60 seconds if no further status is received.

🎯 Conclusion: Turning Silence into Conversation

The Call Received Webhook is the "Emergency Beacon" of your integration. By building an architecture that listens to voice attempts and converts them into chat opportunities, you move your organization from "Missing Connections" to Intelligent Redirection. You build systems that catch every signal, manage every frustration, and bridge every channel gap with engineered precision. In the world of Wawp, a call is not an impossibility; it is a high-priority invitation to a better conversation.

Expected Responses

Explore all possible responses and outcomes from the server. We have documented each status code with data examples to make success and error handling easier.

Webhook Payload Example
application/json
string *
number *
string *
object *
string *
string *
object *
object *

Example

{
"id": "evt_01...",
"timestamp": 1634567890123,
"session": "default",
"metadata": {
  "user.id": "123",
  "user.email": "email@example.com"
  },
"engine": "WEBJS",
"event": "call.received",
"payload": {
  "id": "call_12345",
  "from": "11111111111@c.us",
  "isVideo": false
  },
"me": {
  "id": "11111111111@c.us",
  "lid": "123@lid",
  "pushName": "Instance"
  }
}
Previous TopicChat Archived/Unarchived
Next TopicCall Accepted

Command Palette

Search for a command to run...