From bb06ad259828ae694425964e04689c2ba6aa8376 Mon Sep 17 00:00:00 2001
From: "J.Jason" <130959319+JJasonSun@users.noreply.github.com>
Date: Tue, 22 Sep 2026 15:59:54 +0800
Subject: [PATCH] docs: align webhook and batch call guidance

---
 CHANGELOG.md                                      | 4 ++++
 CONTRIBUTING.md                                   | 4 ++--
 openapi/calle.openapi.yaml                        | 4 ++--
 src/calle/generated/models/create_call_request.py | 2 +-
 4 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index d40d7f0..8e26248 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,9 @@
 # Changelog
 
+## Unreleased
+
+- Clarify request-level webhook configuration and purchased-number requirements for batch calls.
+
 All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 19bed86..c3d08ce 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -44,7 +44,8 @@ or signature headers.
 
 In scope:
 
-- Create a call.
+- Create a call, including multiple recipients when the account has an eligible
+  purchased number selected as its default outbound number.
 - Read a call.
 - Poll until a terminal call result.
 - List call events.
@@ -57,7 +58,6 @@ In scope:
 Out of scope:
 
 - Async client support.
-- Batch calls.
 - Cancel calls.
 - Recurring or scheduled calls.
 - Goal authoring and publishing.
diff --git a/openapi/calle.openapi.yaml b/openapi/calle.openapi.yaml
index 6516406..00bd716 100644
--- a/openapi/calle.openapi.yaml
+++ b/openapi/calle.openapi.yaml
@@ -644,7 +644,7 @@ paths:
       tags:
         - webhooks
       summary: Server Message
-      description: CALL-E sends this request after a call reaches a terminal state and its post-call outcome and requested structured results are finalized. Configure this URL with `webhook_url` on create call or through project-level webhook settings.
+      description: CALL-E sends this request after a call reaches a terminal state and its post-call outcome and requested structured results are finalized. Configure your receiver URL with `webhook_url` when creating a call.
       security: []
       servers:
         - url: https://{yourserver}
@@ -1175,7 +1175,7 @@ components:
           additionalProperties: true
         webhook_url:
           type: string
-          description: Optional per-request HTTPS webhook URL. When provided, CALL-E sends terminal call events to this URL in addition to project-level webhook delivery.
+          description: Optional per-request HTTPS webhook URL. When provided, CALL-E sends terminal call events to this URL after result finalization.
           format: uri
     CallTaskRecipientRequest:
       type: object
diff --git a/src/calle/generated/models/create_call_request.py b/src/calle/generated/models/create_call_request.py
index 1287270..ebcfedf 100644
--- a/src/calle/generated/models/create_call_request.py
+++ b/src/calle/generated/models/create_call_request.py
@@ -65,7 +65,7 @@ class CreateCallRequest:
         metadata (CreateCallRequestMetadata | Unset): Optional caller-owned metadata echoed on the call and webhook
             payloads. Use this for workflow ids, tenant ids, or internal correlation keys.
         webhook_url (str | Unset): Optional per-request HTTPS webhook URL. When provided, CALL-E sends terminal call
-            events to this URL in addition to project-level webhook delivery.
+            events to this URL after result finalization.
     """
 
     task: str