@kirimdev/sdk 1.0.1 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (32) hide show
  1. package/dist/client.d.ts +36 -9
  2. package/dist/client.d.ts.map +1 -1
  3. package/dist/client.js +42 -13
  4. package/dist/client.js.map +1 -1
  5. package/dist/index.d.ts +1 -0
  6. package/dist/index.d.ts.map +1 -1
  7. package/dist/index.js +1 -0
  8. package/dist/index.js.map +1 -1
  9. package/dist/resources/contacts.d.ts +12 -5
  10. package/dist/resources/contacts.d.ts.map +1 -1
  11. package/dist/resources/contacts.js +24 -13
  12. package/dist/resources/contacts.js.map +1 -1
  13. package/dist/resources/conversations.d.ts +10 -3
  14. package/dist/resources/conversations.d.ts.map +1 -1
  15. package/dist/resources/conversations.js +19 -8
  16. package/dist/resources/conversations.js.map +1 -1
  17. package/dist/resources/messages.d.ts +16 -6
  18. package/dist/resources/messages.d.ts.map +1 -1
  19. package/dist/resources/messages.js +24 -10
  20. package/dist/resources/messages.js.map +1 -1
  21. package/dist/resources/phone-number.d.ts +38 -0
  22. package/dist/resources/phone-number.d.ts.map +1 -0
  23. package/dist/resources/phone-number.js +29 -0
  24. package/dist/resources/phone-number.js.map +1 -0
  25. package/dist/resources/templates.d.ts +8 -1
  26. package/dist/resources/templates.d.ts.map +1 -1
  27. package/dist/resources/templates.js +14 -3
  28. package/dist/resources/templates.js.map +1 -1
  29. package/dist/types.d.ts +12 -12
  30. package/dist/types.d.ts.map +1 -1
  31. package/openapi.json +575 -77
  32. package/package.json +1 -1
package/openapi.json CHANGED
@@ -26,7 +26,7 @@
26
26
  },
27
27
  {
28
28
  "name": "Accounts",
29
- "description": "Inspect the WhatsApp accounts connected to your organization. Used to look up the `phone_number` value passed as `from` on multi-account sends."
29
+ "description": "Inspect the WhatsApp accounts connected to your organization. Each account exposes its Meta `business_phone_number_id` — the value used in `/{phone_number_id}/...` paths to address it (Meta-style)."
30
30
  },
31
31
  {
32
32
  "name": "Messages",
@@ -262,6 +262,14 @@
262
262
  "account"
263
263
  ]
264
264
  },
265
+ "phone_number_id": {
266
+ "type": [
267
+ "string",
268
+ "null"
269
+ ],
270
+ "description": "Meta WhatsApp Business `phone_number_id`. Use as the `{phone_number_id}` path parameter in `/v1/{phone_number_id}/...` endpoints. Nullable while onboarding is in flight.",
271
+ "example": "106540352242922"
272
+ },
265
273
  "phone_number": {
266
274
  "type": [
267
275
  "string",
@@ -284,6 +292,7 @@
284
292
  },
285
293
  "required": [
286
294
  "object",
295
+ "phone_number_id",
287
296
  "phone_number",
288
297
  "name",
289
298
  "status"
@@ -1916,7 +1925,7 @@
1916
1925
  "Accounts"
1917
1926
  ],
1918
1927
  "summary": "List connected WhatsApp accounts",
1919
- "description": "List the WhatsApp accounts attached to the calling organization. The returned `phone_number` is the value to pass as `from` on send / create-contact requests when the org has more than one account. Defaults to `status=connected` because that's the only state in which `from` resolves; pass `status=all` to inspect onboarding-in-progress or disconnected accounts. Response is intentionally not paginated.",
1928
+ "description": "List the WhatsApp accounts attached to the calling organization. The returned `business_phone_number_id` is the value to use in `/{phone_number_id}/...` path-based endpoints (Meta-style — sender comes from the URL, not the body). Defaults to `status=connected` because that's the only state in which sends are accepted; pass `status=all` to inspect onboarding-in-progress or disconnected accounts. Response is intentionally not paginated.",
1920
1929
  "security": [
1921
1930
  {
1922
1931
  "bearerAuth": []
@@ -1990,19 +1999,28 @@
1990
1999
  }
1991
2000
  }
1992
2001
  },
1993
- "/messages": {
2002
+ "/{phone_number_id}/messages": {
1994
2003
  "post": {
1995
2004
  "tags": [
1996
2005
  "Messages"
1997
2006
  ],
1998
2007
  "summary": "Send a WhatsApp message",
1999
- "description": "Send a message of any supported type (text, template, image, document, video, audio, interactive). Pass `Idempotency-Key` to safely retry on network failure.",
2008
+ "description": "Send a message of any supported type (text, template, image, document, video, audio, interactive). Body shape mirrors the Meta WhatsApp Cloud API — `messaging_product` is required and media variants accept either `link` (hosted URL) or `id` (Meta uploaded media). The sender is the WhatsApp account identified by `phone_number_id` in the URL path; there is no `from` field in the body. Pass `Idempotency-Key` to safely retry on network failure.",
2000
2009
  "security": [
2001
2010
  {
2002
2011
  "bearerAuth": []
2003
2012
  }
2004
2013
  ],
2005
2014
  "parameters": [
2015
+ {
2016
+ "schema": {
2017
+ "type": "string",
2018
+ "pattern": "^\\d{6,20}$"
2019
+ },
2020
+ "required": true,
2021
+ "name": "phone_number_id",
2022
+ "in": "path"
2023
+ },
2006
2024
  {
2007
2025
  "schema": {
2008
2026
  "type": "string",
@@ -2021,13 +2039,20 @@
2021
2039
  {
2022
2040
  "type": "object",
2023
2041
  "properties": {
2024
- "from": {
2042
+ "messaging_product": {
2025
2043
  "type": "string",
2026
- "pattern": "^\\+[1-9]\\d{6,14}$"
2044
+ "enum": [
2045
+ "whatsapp"
2046
+ ]
2027
2047
  },
2028
- "to": {
2048
+ "recipient_type": {
2029
2049
  "type": "string",
2030
- "pattern": "^\\+[1-9]\\d{6,14}$"
2050
+ "enum": [
2051
+ "individual"
2052
+ ]
2053
+ },
2054
+ "to": {
2055
+ "type": "string"
2031
2056
  },
2032
2057
  "type": {
2033
2058
  "type": "string",
@@ -2042,6 +2067,9 @@
2042
2067
  "type": "string",
2043
2068
  "minLength": 1,
2044
2069
  "maxLength": 4096
2070
+ },
2071
+ "preview_url": {
2072
+ "type": "boolean"
2045
2073
  }
2046
2074
  },
2047
2075
  "required": [
@@ -2050,6 +2078,7 @@
2050
2078
  }
2051
2079
  },
2052
2080
  "required": [
2081
+ "messaging_product",
2053
2082
  "to",
2054
2083
  "type",
2055
2084
  "text"
@@ -2058,13 +2087,20 @@
2058
2087
  {
2059
2088
  "type": "object",
2060
2089
  "properties": {
2061
- "from": {
2090
+ "messaging_product": {
2062
2091
  "type": "string",
2063
- "pattern": "^\\+[1-9]\\d{6,14}$"
2092
+ "enum": [
2093
+ "whatsapp"
2094
+ ]
2064
2095
  },
2065
- "to": {
2096
+ "recipient_type": {
2066
2097
  "type": "string",
2067
- "pattern": "^\\+[1-9]\\d{6,14}$"
2098
+ "enum": [
2099
+ "individual"
2100
+ ]
2101
+ },
2102
+ "to": {
2103
+ "type": "string"
2068
2104
  },
2069
2105
  "type": {
2070
2106
  "type": "string",
@@ -2075,10 +2111,15 @@
2075
2111
  "image": {
2076
2112
  "type": "object",
2077
2113
  "properties": {
2078
- "url": {
2114
+ "link": {
2079
2115
  "type": "string",
2080
2116
  "format": "uri"
2081
2117
  },
2118
+ "id": {
2119
+ "type": "string",
2120
+ "minLength": 1,
2121
+ "maxLength": 255
2122
+ },
2082
2123
  "caption": {
2083
2124
  "type": "string",
2084
2125
  "maxLength": 1024
@@ -2087,13 +2128,11 @@
2087
2128
  "type": "string",
2088
2129
  "maxLength": 255
2089
2130
  }
2090
- },
2091
- "required": [
2092
- "url"
2093
- ]
2131
+ }
2094
2132
  }
2095
2133
  },
2096
2134
  "required": [
2135
+ "messaging_product",
2097
2136
  "to",
2098
2137
  "type",
2099
2138
  "image"
@@ -2102,13 +2141,20 @@
2102
2141
  {
2103
2142
  "type": "object",
2104
2143
  "properties": {
2105
- "from": {
2144
+ "messaging_product": {
2106
2145
  "type": "string",
2107
- "pattern": "^\\+[1-9]\\d{6,14}$"
2146
+ "enum": [
2147
+ "whatsapp"
2148
+ ]
2108
2149
  },
2109
- "to": {
2150
+ "recipient_type": {
2110
2151
  "type": "string",
2111
- "pattern": "^\\+[1-9]\\d{6,14}$"
2152
+ "enum": [
2153
+ "individual"
2154
+ ]
2155
+ },
2156
+ "to": {
2157
+ "type": "string"
2112
2158
  },
2113
2159
  "type": {
2114
2160
  "type": "string",
@@ -2119,10 +2165,15 @@
2119
2165
  "document": {
2120
2166
  "type": "object",
2121
2167
  "properties": {
2122
- "url": {
2168
+ "link": {
2123
2169
  "type": "string",
2124
2170
  "format": "uri"
2125
2171
  },
2172
+ "id": {
2173
+ "type": "string",
2174
+ "minLength": 1,
2175
+ "maxLength": 255
2176
+ },
2126
2177
  "caption": {
2127
2178
  "type": "string",
2128
2179
  "maxLength": 1024
@@ -2131,13 +2182,11 @@
2131
2182
  "type": "string",
2132
2183
  "maxLength": 255
2133
2184
  }
2134
- },
2135
- "required": [
2136
- "url"
2137
- ]
2185
+ }
2138
2186
  }
2139
2187
  },
2140
2188
  "required": [
2189
+ "messaging_product",
2141
2190
  "to",
2142
2191
  "type",
2143
2192
  "document"
@@ -2146,13 +2195,20 @@
2146
2195
  {
2147
2196
  "type": "object",
2148
2197
  "properties": {
2149
- "from": {
2198
+ "messaging_product": {
2199
+ "type": "string",
2200
+ "enum": [
2201
+ "whatsapp"
2202
+ ]
2203
+ },
2204
+ "recipient_type": {
2150
2205
  "type": "string",
2151
- "pattern": "^\\+[1-9]\\d{6,14}$"
2206
+ "enum": [
2207
+ "individual"
2208
+ ]
2152
2209
  },
2153
2210
  "to": {
2154
- "type": "string",
2155
- "pattern": "^\\+[1-9]\\d{6,14}$"
2211
+ "type": "string"
2156
2212
  },
2157
2213
  "type": {
2158
2214
  "type": "string",
@@ -2163,10 +2219,15 @@
2163
2219
  "video": {
2164
2220
  "type": "object",
2165
2221
  "properties": {
2166
- "url": {
2222
+ "link": {
2167
2223
  "type": "string",
2168
2224
  "format": "uri"
2169
2225
  },
2226
+ "id": {
2227
+ "type": "string",
2228
+ "minLength": 1,
2229
+ "maxLength": 255
2230
+ },
2170
2231
  "caption": {
2171
2232
  "type": "string",
2172
2233
  "maxLength": 1024
@@ -2175,13 +2236,11 @@
2175
2236
  "type": "string",
2176
2237
  "maxLength": 255
2177
2238
  }
2178
- },
2179
- "required": [
2180
- "url"
2181
- ]
2239
+ }
2182
2240
  }
2183
2241
  },
2184
2242
  "required": [
2243
+ "messaging_product",
2185
2244
  "to",
2186
2245
  "type",
2187
2246
  "video"
@@ -2190,13 +2249,20 @@
2190
2249
  {
2191
2250
  "type": "object",
2192
2251
  "properties": {
2193
- "from": {
2252
+ "messaging_product": {
2194
2253
  "type": "string",
2195
- "pattern": "^\\+[1-9]\\d{6,14}$"
2254
+ "enum": [
2255
+ "whatsapp"
2256
+ ]
2196
2257
  },
2197
- "to": {
2258
+ "recipient_type": {
2198
2259
  "type": "string",
2199
- "pattern": "^\\+[1-9]\\d{6,14}$"
2260
+ "enum": [
2261
+ "individual"
2262
+ ]
2263
+ },
2264
+ "to": {
2265
+ "type": "string"
2200
2266
  },
2201
2267
  "type": {
2202
2268
  "type": "string",
@@ -2207,10 +2273,15 @@
2207
2273
  "audio": {
2208
2274
  "type": "object",
2209
2275
  "properties": {
2210
- "url": {
2276
+ "link": {
2211
2277
  "type": "string",
2212
2278
  "format": "uri"
2213
2279
  },
2280
+ "id": {
2281
+ "type": "string",
2282
+ "minLength": 1,
2283
+ "maxLength": 255
2284
+ },
2214
2285
  "caption": {
2215
2286
  "type": "string",
2216
2287
  "maxLength": 1024
@@ -2219,13 +2290,11 @@
2219
2290
  "type": "string",
2220
2291
  "maxLength": 255
2221
2292
  }
2222
- },
2223
- "required": [
2224
- "url"
2225
- ]
2293
+ }
2226
2294
  }
2227
2295
  },
2228
2296
  "required": [
2297
+ "messaging_product",
2229
2298
  "to",
2230
2299
  "type",
2231
2300
  "audio"
@@ -2234,13 +2303,20 @@
2234
2303
  {
2235
2304
  "type": "object",
2236
2305
  "properties": {
2237
- "from": {
2306
+ "messaging_product": {
2238
2307
  "type": "string",
2239
- "pattern": "^\\+[1-9]\\d{6,14}$"
2308
+ "enum": [
2309
+ "whatsapp"
2310
+ ]
2240
2311
  },
2241
- "to": {
2312
+ "recipient_type": {
2242
2313
  "type": "string",
2243
- "pattern": "^\\+[1-9]\\d{6,14}$"
2314
+ "enum": [
2315
+ "individual"
2316
+ ]
2317
+ },
2318
+ "to": {
2319
+ "type": "string"
2244
2320
  },
2245
2321
  "type": {
2246
2322
  "type": "string",
@@ -2256,8 +2332,29 @@
2256
2332
  "minLength": 1
2257
2333
  },
2258
2334
  "language": {
2259
- "type": "string",
2260
- "minLength": 2
2335
+ "anyOf": [
2336
+ {
2337
+ "type": "string",
2338
+ "minLength": 2,
2339
+ "maxLength": 15
2340
+ },
2341
+ {
2342
+ "type": "object",
2343
+ "properties": {
2344
+ "code": {
2345
+ "type": "string",
2346
+ "minLength": 2,
2347
+ "maxLength": 15
2348
+ },
2349
+ "policy": {
2350
+ "type": "string"
2351
+ }
2352
+ },
2353
+ "required": [
2354
+ "code"
2355
+ ]
2356
+ }
2357
+ ]
2261
2358
  },
2262
2359
  "components": {
2263
2360
  "type": "array",
@@ -2306,6 +2403,7 @@
2306
2403
  }
2307
2404
  },
2308
2405
  "required": [
2406
+ "messaging_product",
2309
2407
  "to",
2310
2408
  "type",
2311
2409
  "template"
@@ -2314,13 +2412,20 @@
2314
2412
  {
2315
2413
  "type": "object",
2316
2414
  "properties": {
2317
- "from": {
2415
+ "messaging_product": {
2318
2416
  "type": "string",
2319
- "pattern": "^\\+[1-9]\\d{6,14}$"
2417
+ "enum": [
2418
+ "whatsapp"
2419
+ ]
2320
2420
  },
2321
- "to": {
2421
+ "recipient_type": {
2322
2422
  "type": "string",
2323
- "pattern": "^\\+[1-9]\\d{6,14}$"
2423
+ "enum": [
2424
+ "individual"
2425
+ ]
2426
+ },
2427
+ "to": {
2428
+ "type": "string"
2324
2429
  },
2325
2430
  "type": {
2326
2431
  "type": "string",
@@ -2729,6 +2834,7 @@
2729
2834
  }
2730
2835
  },
2731
2836
  "required": [
2837
+ "messaging_product",
2732
2838
  "to",
2733
2839
  "type",
2734
2840
  "interactive"
@@ -2770,6 +2876,16 @@
2770
2876
  }
2771
2877
  }
2772
2878
  },
2879
+ "404": {
2880
+ "description": "Resource not found",
2881
+ "content": {
2882
+ "application/json": {
2883
+ "schema": {
2884
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
2885
+ }
2886
+ }
2887
+ }
2888
+ },
2773
2889
  "422": {
2774
2890
  "description": "Semantic failure (e.g. idempotency key reuse)",
2775
2891
  "content": {
@@ -2817,13 +2933,22 @@
2817
2933
  "Messages"
2818
2934
  ],
2819
2935
  "summary": "List messages",
2820
- "description": "List messages across the organization. Filter by `conversation_id`, `direction`, `status`, or a `created_after`/`created_before` window.",
2936
+ "description": "List messages for the WhatsApp account identified by `phone_number_id`. Filter by `conversation_id`, `direction`, `status`, or a `created_after`/`created_before` window.",
2821
2937
  "security": [
2822
2938
  {
2823
2939
  "bearerAuth": []
2824
2940
  }
2825
2941
  ],
2826
2942
  "parameters": [
2943
+ {
2944
+ "schema": {
2945
+ "type": "string",
2946
+ "pattern": "^\\d{6,20}$"
2947
+ },
2948
+ "required": true,
2949
+ "name": "phone_number_id",
2950
+ "in": "path"
2951
+ },
2827
2952
  {
2828
2953
  "schema": {
2829
2954
  "type": "string",
@@ -2927,6 +3052,26 @@
2927
3052
  }
2928
3053
  }
2929
3054
  },
3055
+ "404": {
3056
+ "description": "Resource not found",
3057
+ "content": {
3058
+ "application/json": {
3059
+ "schema": {
3060
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
3061
+ }
3062
+ }
3063
+ }
3064
+ },
3065
+ "422": {
3066
+ "description": "Semantic failure (e.g. idempotency key reuse)",
3067
+ "content": {
3068
+ "application/json": {
3069
+ "schema": {
3070
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
3071
+ }
3072
+ }
3073
+ }
3074
+ },
2930
3075
  "429": {
2931
3076
  "description": "Rate limit exceeded",
2932
3077
  "content": {
@@ -2950,7 +3095,7 @@
2950
3095
  }
2951
3096
  }
2952
3097
  },
2953
- "/messages/{id}": {
3098
+ "/{phone_number_id}/messages/{id}": {
2954
3099
  "get": {
2955
3100
  "tags": [
2956
3101
  "Messages"
@@ -2962,6 +3107,15 @@
2962
3107
  }
2963
3108
  ],
2964
3109
  "parameters": [
3110
+ {
3111
+ "schema": {
3112
+ "type": "string",
3113
+ "pattern": "^\\d{6,20}$"
3114
+ },
3115
+ "required": true,
3116
+ "name": "phone_number_id",
3117
+ "in": "path"
3118
+ },
2965
3119
  {
2966
3120
  "schema": {
2967
3121
  "type": "string",
@@ -3013,6 +3167,16 @@
3013
3167
  }
3014
3168
  }
3015
3169
  },
3170
+ "422": {
3171
+ "description": "Semantic failure (e.g. idempotency key reuse)",
3172
+ "content": {
3173
+ "application/json": {
3174
+ "schema": {
3175
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
3176
+ }
3177
+ }
3178
+ }
3179
+ },
3016
3180
  "429": {
3017
3181
  "description": "Rate limit exceeded",
3018
3182
  "content": {
@@ -3036,19 +3200,28 @@
3036
3200
  }
3037
3201
  }
3038
3202
  },
3039
- "/templates": {
3203
+ "/{phone_number_id}/templates": {
3040
3204
  "get": {
3041
3205
  "tags": [
3042
3206
  "Templates"
3043
3207
  ],
3044
3208
  "summary": "List approved templates",
3045
- "description": "List templates synced from Meta across every connected WhatsApp account in the organization. Default filter is `status=approved`.",
3209
+ "description": "List templates synced from Meta for the WhatsApp account identified by `phone_number_id`. Default filter is `status=approved`.",
3046
3210
  "security": [
3047
3211
  {
3048
3212
  "bearerAuth": []
3049
3213
  }
3050
3214
  ],
3051
3215
  "parameters": [
3216
+ {
3217
+ "schema": {
3218
+ "type": "string",
3219
+ "pattern": "^\\d{6,20}$"
3220
+ },
3221
+ "required": true,
3222
+ "name": "phone_number_id",
3223
+ "in": "path"
3224
+ },
3052
3225
  {
3053
3226
  "schema": {
3054
3227
  "type": "string",
@@ -3123,6 +3296,26 @@
3123
3296
  }
3124
3297
  }
3125
3298
  },
3299
+ "404": {
3300
+ "description": "Resource not found",
3301
+ "content": {
3302
+ "application/json": {
3303
+ "schema": {
3304
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
3305
+ }
3306
+ }
3307
+ }
3308
+ },
3309
+ "422": {
3310
+ "description": "Semantic failure (e.g. idempotency key reuse)",
3311
+ "content": {
3312
+ "application/json": {
3313
+ "schema": {
3314
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
3315
+ }
3316
+ }
3317
+ }
3318
+ },
3126
3319
  "429": {
3127
3320
  "description": "Rate limit exceeded",
3128
3321
  "content": {
@@ -3146,7 +3339,7 @@
3146
3339
  }
3147
3340
  }
3148
3341
  },
3149
- "/templates/{name}": {
3342
+ "/{phone_number_id}/templates/{name}": {
3150
3343
  "get": {
3151
3344
  "tags": [
3152
3345
  "Templates"
@@ -3158,6 +3351,15 @@
3158
3351
  }
3159
3352
  ],
3160
3353
  "parameters": [
3354
+ {
3355
+ "schema": {
3356
+ "type": "string",
3357
+ "pattern": "^\\d{6,20}$"
3358
+ },
3359
+ "required": true,
3360
+ "name": "phone_number_id",
3361
+ "in": "path"
3362
+ },
3161
3363
  {
3162
3364
  "schema": {
3163
3365
  "type": "string",
@@ -3220,6 +3422,16 @@
3220
3422
  }
3221
3423
  }
3222
3424
  },
3425
+ "422": {
3426
+ "description": "Semantic failure (e.g. idempotency key reuse)",
3427
+ "content": {
3428
+ "application/json": {
3429
+ "schema": {
3430
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
3431
+ }
3432
+ }
3433
+ }
3434
+ },
3223
3435
  "429": {
3224
3436
  "description": "Rate limit exceeded",
3225
3437
  "content": {
@@ -4423,19 +4635,28 @@
4423
4635
  }
4424
4636
  }
4425
4637
  },
4426
- "/conversations": {
4638
+ "/{phone_number_id}/conversations": {
4427
4639
  "get": {
4428
4640
  "tags": [
4429
4641
  "Conversations"
4430
4642
  ],
4431
4643
  "summary": "List conversations",
4432
- "description": "List conversations across every connected WhatsApp account in the organization. Ordered newest-active first by `last_message_at` (NULLS LAST).",
4644
+ "description": "List conversations for the WhatsApp account identified by `phone_number_id`. Ordered newest-active first by `last_message_at` (NULLS LAST).",
4433
4645
  "security": [
4434
4646
  {
4435
4647
  "bearerAuth": []
4436
4648
  }
4437
4649
  ],
4438
4650
  "parameters": [
4651
+ {
4652
+ "schema": {
4653
+ "type": "string",
4654
+ "pattern": "^\\d{6,20}$"
4655
+ },
4656
+ "required": true,
4657
+ "name": "phone_number_id",
4658
+ "in": "path"
4659
+ },
4439
4660
  {
4440
4661
  "schema": {
4441
4662
  "type": "string",
@@ -4507,6 +4728,26 @@
4507
4728
  }
4508
4729
  }
4509
4730
  },
4731
+ "404": {
4732
+ "description": "Resource not found",
4733
+ "content": {
4734
+ "application/json": {
4735
+ "schema": {
4736
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
4737
+ }
4738
+ }
4739
+ }
4740
+ },
4741
+ "422": {
4742
+ "description": "Semantic failure (e.g. idempotency key reuse)",
4743
+ "content": {
4744
+ "application/json": {
4745
+ "schema": {
4746
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
4747
+ }
4748
+ }
4749
+ }
4750
+ },
4510
4751
  "429": {
4511
4752
  "description": "Rate limit exceeded",
4512
4753
  "content": {
@@ -4530,7 +4771,7 @@
4530
4771
  }
4531
4772
  }
4532
4773
  },
4533
- "/conversations/{id}": {
4774
+ "/{phone_number_id}/conversations/{id}": {
4534
4775
  "get": {
4535
4776
  "tags": [
4536
4777
  "Conversations"
@@ -4542,6 +4783,15 @@
4542
4783
  }
4543
4784
  ],
4544
4785
  "parameters": [
4786
+ {
4787
+ "schema": {
4788
+ "type": "string",
4789
+ "pattern": "^\\d{6,20}$"
4790
+ },
4791
+ "required": true,
4792
+ "name": "phone_number_id",
4793
+ "in": "path"
4794
+ },
4545
4795
  {
4546
4796
  "schema": {
4547
4797
  "type": "string",
@@ -4593,6 +4843,16 @@
4593
4843
  }
4594
4844
  }
4595
4845
  },
4846
+ "422": {
4847
+ "description": "Semantic failure (e.g. idempotency key reuse)",
4848
+ "content": {
4849
+ "application/json": {
4850
+ "schema": {
4851
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
4852
+ }
4853
+ }
4854
+ }
4855
+ },
4596
4856
  "429": {
4597
4857
  "description": "Rate limit exceeded",
4598
4858
  "content": {
@@ -4627,6 +4887,15 @@
4627
4887
  }
4628
4888
  ],
4629
4889
  "parameters": [
4890
+ {
4891
+ "schema": {
4892
+ "type": "string",
4893
+ "pattern": "^\\d{6,20}$"
4894
+ },
4895
+ "required": true,
4896
+ "name": "phone_number_id",
4897
+ "in": "path"
4898
+ },
4630
4899
  {
4631
4900
  "schema": {
4632
4901
  "type": "string",
@@ -4705,6 +4974,16 @@
4705
4974
  }
4706
4975
  }
4707
4976
  },
4977
+ "422": {
4978
+ "description": "Semantic failure (e.g. idempotency key reuse)",
4979
+ "content": {
4980
+ "application/json": {
4981
+ "schema": {
4982
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
4983
+ }
4984
+ }
4985
+ }
4986
+ },
4708
4987
  "429": {
4709
4988
  "description": "Rate limit exceeded",
4710
4989
  "content": {
@@ -4728,19 +5007,28 @@
4728
5007
  }
4729
5008
  }
4730
5009
  },
4731
- "/contacts": {
5010
+ "/{phone_number_id}/contacts": {
4732
5011
  "get": {
4733
5012
  "tags": [
4734
5013
  "Contacts"
4735
5014
  ],
4736
5015
  "summary": "List contacts",
4737
- "description": "List contacts in the organization. Filter by exact `phone` (E.164) or partial `search` (matches name and email).",
5016
+ "description": "List contacts attached to the WhatsApp account identified by `phone_number_id`. Filter by exact `phone` (E.164) or partial `search` (matches name and email).",
4738
5017
  "security": [
4739
5018
  {
4740
5019
  "bearerAuth": []
4741
5020
  }
4742
5021
  ],
4743
5022
  "parameters": [
5023
+ {
5024
+ "schema": {
5025
+ "type": "string",
5026
+ "pattern": "^\\d{6,20}$"
5027
+ },
5028
+ "required": true,
5029
+ "name": "phone_number_id",
5030
+ "in": "path"
5031
+ },
4744
5032
  {
4745
5033
  "schema": {
4746
5034
  "type": "string",
@@ -4809,6 +5097,26 @@
4809
5097
  }
4810
5098
  }
4811
5099
  },
5100
+ "404": {
5101
+ "description": "Resource not found",
5102
+ "content": {
5103
+ "application/json": {
5104
+ "schema": {
5105
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
5106
+ }
5107
+ }
5108
+ }
5109
+ },
5110
+ "422": {
5111
+ "description": "Semantic failure (e.g. idempotency key reuse)",
5112
+ "content": {
5113
+ "application/json": {
5114
+ "schema": {
5115
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
5116
+ }
5117
+ }
5118
+ }
5119
+ },
4812
5120
  "429": {
4813
5121
  "description": "Rate limit exceeded",
4814
5122
  "content": {
@@ -4836,22 +5144,29 @@
4836
5144
  "Contacts"
4837
5145
  ],
4838
5146
  "summary": "Create a contact",
4839
- "description": "Create a contact attached to a connected WhatsApp account. Single-account orgs auto-resolve; multi-account orgs MUST pass `from`.",
5147
+ "description": "Create a contact attached to the WhatsApp account identified by `phone_number_id` in the URL path.",
4840
5148
  "security": [
4841
5149
  {
4842
5150
  "bearerAuth": []
4843
5151
  }
4844
5152
  ],
5153
+ "parameters": [
5154
+ {
5155
+ "schema": {
5156
+ "type": "string",
5157
+ "pattern": "^\\d{6,20}$"
5158
+ },
5159
+ "required": true,
5160
+ "name": "phone_number_id",
5161
+ "in": "path"
5162
+ }
5163
+ ],
4845
5164
  "requestBody": {
4846
5165
  "content": {
4847
5166
  "application/json": {
4848
5167
  "schema": {
4849
5168
  "type": "object",
4850
5169
  "properties": {
4851
- "from": {
4852
- "type": "string",
4853
- "pattern": "^\\+[1-9]\\d{6,14}$"
4854
- },
4855
5170
  "phone_number": {
4856
5171
  "type": "string",
4857
5172
  "pattern": "^\\+[1-9]\\d{6,14}$"
@@ -4912,6 +5227,16 @@
4912
5227
  }
4913
5228
  }
4914
5229
  },
5230
+ "404": {
5231
+ "description": "Resource not found",
5232
+ "content": {
5233
+ "application/json": {
5234
+ "schema": {
5235
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
5236
+ }
5237
+ }
5238
+ }
5239
+ },
4915
5240
  "422": {
4916
5241
  "description": "Semantic failure (e.g. idempotency key reuse)",
4917
5242
  "content": {
@@ -4945,7 +5270,7 @@
4945
5270
  }
4946
5271
  }
4947
5272
  },
4948
- "/contacts/{id}": {
5273
+ "/{phone_number_id}/contacts/{id}": {
4949
5274
  "get": {
4950
5275
  "tags": [
4951
5276
  "Contacts"
@@ -4957,6 +5282,15 @@
4957
5282
  }
4958
5283
  ],
4959
5284
  "parameters": [
5285
+ {
5286
+ "schema": {
5287
+ "type": "string",
5288
+ "pattern": "^\\d{6,20}$"
5289
+ },
5290
+ "required": true,
5291
+ "name": "phone_number_id",
5292
+ "in": "path"
5293
+ },
4960
5294
  {
4961
5295
  "schema": {
4962
5296
  "type": "string",
@@ -5008,6 +5342,16 @@
5008
5342
  }
5009
5343
  }
5010
5344
  },
5345
+ "422": {
5346
+ "description": "Semantic failure (e.g. idempotency key reuse)",
5347
+ "content": {
5348
+ "application/json": {
5349
+ "schema": {
5350
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
5351
+ }
5352
+ }
5353
+ }
5354
+ },
5011
5355
  "429": {
5012
5356
  "description": "Rate limit exceeded",
5013
5357
  "content": {
@@ -5042,6 +5386,15 @@
5042
5386
  }
5043
5387
  ],
5044
5388
  "parameters": [
5389
+ {
5390
+ "schema": {
5391
+ "type": "string",
5392
+ "pattern": "^\\d{6,20}$"
5393
+ },
5394
+ "required": true,
5395
+ "name": "phone_number_id",
5396
+ "in": "path"
5397
+ },
5045
5398
  {
5046
5399
  "schema": {
5047
5400
  "type": "string",
@@ -5137,6 +5490,16 @@
5137
5490
  }
5138
5491
  }
5139
5492
  },
5493
+ "422": {
5494
+ "description": "Semantic failure (e.g. idempotency key reuse)",
5495
+ "content": {
5496
+ "application/json": {
5497
+ "schema": {
5498
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
5499
+ }
5500
+ }
5501
+ }
5502
+ },
5140
5503
  "429": {
5141
5504
  "description": "Rate limit exceeded",
5142
5505
  "content": {
@@ -5171,6 +5534,15 @@
5171
5534
  }
5172
5535
  ],
5173
5536
  "parameters": [
5537
+ {
5538
+ "schema": {
5539
+ "type": "string",
5540
+ "pattern": "^\\d{6,20}$"
5541
+ },
5542
+ "required": true,
5543
+ "name": "phone_number_id",
5544
+ "in": "path"
5545
+ },
5174
5546
  {
5175
5547
  "schema": {
5176
5548
  "type": "string",
@@ -5222,6 +5594,16 @@
5222
5594
  }
5223
5595
  }
5224
5596
  },
5597
+ "422": {
5598
+ "description": "Semantic failure (e.g. idempotency key reuse)",
5599
+ "content": {
5600
+ "application/json": {
5601
+ "schema": {
5602
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
5603
+ }
5604
+ }
5605
+ }
5606
+ },
5225
5607
  "429": {
5226
5608
  "description": "Rate limit exceeded",
5227
5609
  "content": {
@@ -5245,7 +5627,7 @@
5245
5627
  }
5246
5628
  }
5247
5629
  },
5248
- "/messages/{id}/media": {
5630
+ "/{phone_number_id}/messages/{id}/media": {
5249
5631
  "get": {
5250
5632
  "tags": [
5251
5633
  "Messages"
@@ -5258,6 +5640,15 @@
5258
5640
  }
5259
5641
  ],
5260
5642
  "parameters": [
5643
+ {
5644
+ "schema": {
5645
+ "type": "string",
5646
+ "pattern": "^\\d{6,20}$"
5647
+ },
5648
+ "required": true,
5649
+ "name": "phone_number_id",
5650
+ "in": "path"
5651
+ },
5261
5652
  {
5262
5653
  "schema": {
5263
5654
  "type": "string",
@@ -5310,6 +5701,16 @@
5310
5701
  }
5311
5702
  }
5312
5703
  },
5704
+ "422": {
5705
+ "description": "Semantic failure (e.g. idempotency key reuse)",
5706
+ "content": {
5707
+ "application/json": {
5708
+ "schema": {
5709
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
5710
+ }
5711
+ }
5712
+ }
5713
+ },
5313
5714
  "429": {
5314
5715
  "description": "Rate limit exceeded",
5315
5716
  "content": {
@@ -5333,7 +5734,7 @@
5333
5734
  }
5334
5735
  }
5335
5736
  },
5336
- "/contacts/{id}/labels": {
5737
+ "/{phone_number_id}/contacts/{id}/labels": {
5337
5738
  "post": {
5338
5739
  "tags": [
5339
5740
  "Contacts"
@@ -5346,6 +5747,15 @@
5346
5747
  }
5347
5748
  ],
5348
5749
  "parameters": [
5750
+ {
5751
+ "schema": {
5752
+ "type": "string",
5753
+ "pattern": "^\\d{6,20}$"
5754
+ },
5755
+ "required": true,
5756
+ "name": "phone_number_id",
5757
+ "in": "path"
5758
+ },
5349
5759
  {
5350
5760
  "schema": {
5351
5761
  "type": "string",
@@ -5415,6 +5825,16 @@
5415
5825
  }
5416
5826
  }
5417
5827
  },
5828
+ "422": {
5829
+ "description": "Semantic failure (e.g. idempotency key reuse)",
5830
+ "content": {
5831
+ "application/json": {
5832
+ "schema": {
5833
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
5834
+ }
5835
+ }
5836
+ }
5837
+ },
5418
5838
  "429": {
5419
5839
  "description": "Rate limit exceeded",
5420
5840
  "content": {
@@ -5438,7 +5858,7 @@
5438
5858
  }
5439
5859
  }
5440
5860
  },
5441
- "/contacts/{id}/labels/{label_id}": {
5861
+ "/{phone_number_id}/contacts/{id}/labels/{label_id}": {
5442
5862
  "delete": {
5443
5863
  "tags": [
5444
5864
  "Contacts"
@@ -5450,6 +5870,15 @@
5450
5870
  }
5451
5871
  ],
5452
5872
  "parameters": [
5873
+ {
5874
+ "schema": {
5875
+ "type": "string",
5876
+ "pattern": "^\\d{6,20}$"
5877
+ },
5878
+ "required": true,
5879
+ "name": "phone_number_id",
5880
+ "in": "path"
5881
+ },
5453
5882
  {
5454
5883
  "schema": {
5455
5884
  "type": "string",
@@ -5510,6 +5939,16 @@
5510
5939
  }
5511
5940
  }
5512
5941
  },
5942
+ "422": {
5943
+ "description": "Semantic failure (e.g. idempotency key reuse)",
5944
+ "content": {
5945
+ "application/json": {
5946
+ "schema": {
5947
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
5948
+ }
5949
+ }
5950
+ }
5951
+ },
5513
5952
  "429": {
5514
5953
  "description": "Rate limit exceeded",
5515
5954
  "content": {
@@ -5533,18 +5972,29 @@
5533
5972
  }
5534
5973
  }
5535
5974
  },
5536
- "/contacts/bulk_label": {
5975
+ "/{phone_number_id}/contacts/bulk_label": {
5537
5976
  "post": {
5538
5977
  "tags": [
5539
5978
  "Contacts"
5540
5979
  ],
5541
5980
  "summary": "Attach or detach a label across many contacts",
5542
- "description": "Apply or remove a label from up to 1000 contacts in a single transaction. Cross-org or team-mismatched contacts are silently skipped and counted.",
5981
+ "description": "Apply or remove a label from up to 1000 contacts in a single transaction. Contacts not owned by the path-scoped account are silently skipped and counted under `skipped_cross_org`.",
5543
5982
  "security": [
5544
5983
  {
5545
5984
  "bearerAuth": []
5546
5985
  }
5547
5986
  ],
5987
+ "parameters": [
5988
+ {
5989
+ "schema": {
5990
+ "type": "string",
5991
+ "pattern": "^\\d{6,20}$"
5992
+ },
5993
+ "required": true,
5994
+ "name": "phone_number_id",
5995
+ "in": "path"
5996
+ }
5997
+ ],
5548
5998
  "requestBody": {
5549
5999
  "content": {
5550
6000
  "application/json": {
@@ -5622,6 +6072,16 @@
5622
6072
  }
5623
6073
  }
5624
6074
  },
6075
+ "422": {
6076
+ "description": "Semantic failure (e.g. idempotency key reuse)",
6077
+ "content": {
6078
+ "application/json": {
6079
+ "schema": {
6080
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
6081
+ }
6082
+ }
6083
+ }
6084
+ },
5625
6085
  "429": {
5626
6086
  "description": "Rate limit exceeded",
5627
6087
  "content": {
@@ -5645,7 +6105,7 @@
5645
6105
  }
5646
6106
  }
5647
6107
  },
5648
- "/conversations/{id}/labels": {
6108
+ "/{phone_number_id}/conversations/{id}/labels": {
5649
6109
  "post": {
5650
6110
  "tags": [
5651
6111
  "Conversations"
@@ -5657,6 +6117,15 @@
5657
6117
  }
5658
6118
  ],
5659
6119
  "parameters": [
6120
+ {
6121
+ "schema": {
6122
+ "type": "string",
6123
+ "pattern": "^\\d{6,20}$"
6124
+ },
6125
+ "required": true,
6126
+ "name": "phone_number_id",
6127
+ "in": "path"
6128
+ },
5660
6129
  {
5661
6130
  "schema": {
5662
6131
  "type": "string",
@@ -5726,6 +6195,16 @@
5726
6195
  }
5727
6196
  }
5728
6197
  },
6198
+ "422": {
6199
+ "description": "Semantic failure (e.g. idempotency key reuse)",
6200
+ "content": {
6201
+ "application/json": {
6202
+ "schema": {
6203
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
6204
+ }
6205
+ }
6206
+ }
6207
+ },
5729
6208
  "429": {
5730
6209
  "description": "Rate limit exceeded",
5731
6210
  "content": {
@@ -5749,7 +6228,7 @@
5749
6228
  }
5750
6229
  }
5751
6230
  },
5752
- "/conversations/{id}/labels/{label_id}": {
6231
+ "/{phone_number_id}/conversations/{id}/labels/{label_id}": {
5753
6232
  "delete": {
5754
6233
  "tags": [
5755
6234
  "Conversations"
@@ -5761,6 +6240,15 @@
5761
6240
  }
5762
6241
  ],
5763
6242
  "parameters": [
6243
+ {
6244
+ "schema": {
6245
+ "type": "string",
6246
+ "pattern": "^\\d{6,20}$"
6247
+ },
6248
+ "required": true,
6249
+ "name": "phone_number_id",
6250
+ "in": "path"
6251
+ },
5764
6252
  {
5765
6253
  "schema": {
5766
6254
  "type": "string",
@@ -5821,6 +6309,16 @@
5821
6309
  }
5822
6310
  }
5823
6311
  },
6312
+ "422": {
6313
+ "description": "Semantic failure (e.g. idempotency key reuse)",
6314
+ "content": {
6315
+ "application/json": {
6316
+ "schema": {
6317
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
6318
+ }
6319
+ }
6320
+ }
6321
+ },
5824
6322
  "429": {
5825
6323
  "description": "Rate limit exceeded",
5826
6324
  "content": {