Webhooks

Call Rejected

Triggered when an incoming call is declined.

Best practices

  • Mark the call as 'Declined' in your communication history database.

Closing the Voice Loop: Mastering Call Rejected Webhooks

In the ecosystem of digital communication, the termination of an interaction is as significant as its initiation. The [call.rejected] webhook is the definitive "End of Signal" event for a voice or video attempt within the Wawp platform. Whether a call is manually declined by a human operator using a physical device or automatically terminated due to system policy, this event provides your infrastructure with the closure required to maintain an accurate, real-time audit trail of customer engagement.

This guide provides an architectural deep-dive into the strategic value of call termination monitoring, moving beyond "Status Logging" into the realm of Operational Accountability and Customer Experience Synchronization.

🏗️ Architectural Philosophy: The Call as a Finite Session

A WhatsApp call is a synchronous state that consumes resources and attention. The [call.rejected] event serves as the "Garbage Collector" for your communication logic.

1. The Termination Vector

A rejection event can occur due to several distinct triggers, and a premium architecture must account for all of them:

  • Manual Decline: A human agent taps "Decline" on the physical phone or WhatsApp Web.
  • Automated Policy: Your backend logic or a third-party app terminates the call.
  • User Cancellation: The caller hangs up before the call is answered (though this sometimes results in a "Missed" state, Wawp often emits the rejection signal to clear the socket).

2. Identifying the Call Session

The only field in the payload is the [id] of the call. This is by design. The Call ID is the Primary Key that connects the [call.received] event with the [call.rejected] event. Your system must use this ID to "Reconcile" the interaction, moving the call record in your database from RINGING to TERMINATED.

🚀 Strategic Use Cases: Powering Accountable Support Flows

Call rejection monitoring allows you to measure the "Response Gap" and automate the next step in the customer journey.

1. The "Immediate Proactive Chat" Strategy

If a call is rejected, the user is likely at their phone right now. This is the perfect moment for a text-based follow-up. The Strategic Workflow: As soon as [call.rejected] is received, your system checks if it was preceded by a [call.received] event. If so, it instantly sends a message: "Sorry we couldn't take your call right now! We're currently assisting other customers via chat. How can we help you here?" Strategic Value: This turns a "Negative Interaction" (a rejected call) into a "Positive Engagement" (a proactive chat). It demonstrates that your brand is aware, responsive, and ready to assist through alternate channels.

2. Agent Performance and Accountability Mining

In a support center where agents have physical phones, the rejection rate is a key performance indicator (KPI). The Logic: By correlating the [call.rejected] event with the agent assigned to that WhatsApp instance, you can identify patterns of avoided interactions. If an instance consistently rejects 80% of incoming calls during business hours, it indicates a training or staffing issue. This data allows for Evidence-Based Management, moving away from "Feelings" about agent performance toward hard, technical proof of interaction avoidance.

3. CRM History and "Audit of Intent"

A complete CRM record should not just show messages; it should show every attempt at contact. The Data Pattern: When the rejection webhook fires, update the user's timeline with a specialized "Missed/Rejected Call" entry. This gives the next agent to handle the customer a full view of the context: "Customer tried to call 3 times this morning and was declined each time." This allows the agent to apologize for the missed connection, significantly improving the "Personalization Score" of the next interaction.

🛡️ Administrative Mandate: Balancing Physical and Digital Reality

1. The "Physical Sync" Problem

When you use Wawp, you are often using a real WhatsApp account that exists on a physical smartphone. If a human picks up that phone and hits "Decline," the Wawp API receives the [call.rejected] webhook. The Strategic Insight: This webhook is your backend's only way of knowing what the physical human operator did. Use it to keep your digital dashboard "In Sync" with the physical reality of the office. If the phone user is declining calls, your digital bot should probably "Sleep" for a few minutes to avoid conflicting with the human's manual workflow.

2. Guarding against "Zombie Calls"

Without a rejection signal, your custom dashboard might show a "Call in Progress" banner forever if the network drops during the ringing phase. The Strategy: Use the [call.rejected] event as a Global Clear Command. When this event fires, it should forcibly remove any "Active Call" UI elements for that specific [session], ensuring your agents always have an accurate view of the instance's state.

🛡️ Operational Best Practices: Designing for Professional Closure

  • Handling the "Busy" Signal: If your system rejects a call because the agent is already in a chat, use the [call.rejected] event to trigger a "Wait" message. This explains why the call was declined, preventing the user from feeling ignored.
  • Coordinate with Call Received: Always index your calls by ID. If you receive a [call.rejected] for an ID that you never received a [call.received] for, log it as a "Network Anomaly." This helps your technical team identify stability issues with the WhatsApp WebSocket or your server's ingestion lag.
  • The "Zero-Latency" Rule: Like all call events, rejection is extremely time-sensitive. If your follow-up message arrives 10 minutes late, the customer has already moved on to a competitor. Host your rejection handler on your fastest, most reliable infrastructure.

⚙️ Engineering Best Practices: The Validation Loop

  1. Strict ID Mapping: Ensure your database uses the Call ID as a primary key for call-related records. This prevents "ID Collision" and ensures that state updates are applied to the correct interaction.
  2. Verify the Session Scope: In a multi-instance setup, Ensure that the [session] ID provided in the webhook metadata is used to gate your follow-up logic. You don't want a "Sorry we missed you" message being sent from the wrong business line.
  3. Clean up In-Memory States: If you use a cache (like Redis) to track "Active Calls," use the [call.rejected] event to immediately purge the entry for that Call ID. This keeps your cache lean and prevents memory leaks.

🎯 Conclusion: Mastering the Art of the End-Point

The Call Rejected Webhook is the "Final Chapter" of a voice interaction. By building an architecture that listens to this termination signal and converts it into a proactive opportunity, you move your organization from "Abrupt Disconnects" to Seamless Redirection. You build systems that respect human decisions, capture interaction data, and maintain a high-fidelity conversational history with engineered precision. In the world of Wawp, a rejection is not the end of the relationship; it is the strategic trigger for a better, more focused 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.rejected",
"payload": {
  "id": "call_12345"
  },
"me": {
  "id": "11111111111@c.us",
  "lid": "123@lid",
  "pushName": "Instance"
  }
}
Previous TopicCall Accepted
Next TopicLabel Created/Updated

Command Palette

Search for a command to run...