@kirimdev/sdk 1.0.0 → 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 (36) hide show
  1. package/dist/client.d.ts +38 -9
  2. package/dist/client.d.ts.map +1 -1
  3. package/dist/client.js +45 -13
  4. package/dist/client.js.map +1 -1
  5. package/dist/index.d.ts +2 -1
  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/accounts.d.ts +21 -0
  10. package/dist/resources/accounts.d.ts.map +1 -0
  11. package/dist/resources/accounts.js +32 -0
  12. package/dist/resources/accounts.js.map +1 -0
  13. package/dist/resources/contacts.d.ts +12 -5
  14. package/dist/resources/contacts.d.ts.map +1 -1
  15. package/dist/resources/contacts.js +24 -13
  16. package/dist/resources/contacts.js.map +1 -1
  17. package/dist/resources/conversations.d.ts +10 -3
  18. package/dist/resources/conversations.d.ts.map +1 -1
  19. package/dist/resources/conversations.js +19 -8
  20. package/dist/resources/conversations.js.map +1 -1
  21. package/dist/resources/messages.d.ts +16 -6
  22. package/dist/resources/messages.d.ts.map +1 -1
  23. package/dist/resources/messages.js +24 -10
  24. package/dist/resources/messages.js.map +1 -1
  25. package/dist/resources/phone-number.d.ts +38 -0
  26. package/dist/resources/phone-number.d.ts.map +1 -0
  27. package/dist/resources/phone-number.js +29 -0
  28. package/dist/resources/phone-number.js.map +1 -0
  29. package/dist/resources/templates.d.ts +8 -1
  30. package/dist/resources/templates.d.ts.map +1 -1
  31. package/dist/resources/templates.js +14 -3
  32. package/dist/resources/templates.js.map +1 -1
  33. package/dist/types.d.ts +14 -12
  34. package/dist/types.d.ts.map +1 -1
  35. package/openapi.json +723 -76
  36. package/package.json +1 -1
package/openapi.json CHANGED
@@ -24,6 +24,10 @@
24
24
  "name": "Meta",
25
25
  "description": "Liveness probe and API-key introspection."
26
26
  },
27
+ {
28
+ "name": "Accounts",
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
+ },
27
31
  {
28
32
  "name": "Messages",
29
33
  "description": "Send and read WhatsApp messages across every supported content type."
@@ -249,6 +253,51 @@
249
253
  "updated_at"
250
254
  ]
251
255
  },
256
+ "Account": {
257
+ "type": "object",
258
+ "properties": {
259
+ "object": {
260
+ "type": "string",
261
+ "enum": [
262
+ "account"
263
+ ]
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
+ },
273
+ "phone_number": {
274
+ "type": [
275
+ "string",
276
+ "null"
277
+ ],
278
+ "example": "+628111222333"
279
+ },
280
+ "name": {
281
+ "type": [
282
+ "string",
283
+ "null"
284
+ ],
285
+ "example": "Customer Support"
286
+ },
287
+ "status": {
288
+ "type": "string",
289
+ "description": "Lifecycle state of the account (e.g. `connected`, `disconnected`, `degraded`, `onboarding`).",
290
+ "example": "connected"
291
+ }
292
+ },
293
+ "required": [
294
+ "object",
295
+ "phone_number_id",
296
+ "phone_number",
297
+ "name",
298
+ "status"
299
+ ]
300
+ },
252
301
  "WebhookSubscription": {
253
302
  "type": "object",
254
303
  "properties": {
@@ -889,6 +938,35 @@
889
938
  "request_id"
890
939
  ]
891
940
  },
941
+ "ListAccountsResponse": {
942
+ "type": "object",
943
+ "properties": {
944
+ "data": {
945
+ "type": "array",
946
+ "items": {
947
+ "$ref": "#/components/schemas/Account"
948
+ }
949
+ },
950
+ "has_more": {
951
+ "type": "boolean"
952
+ },
953
+ "next_cursor": {
954
+ "type": [
955
+ "string",
956
+ "null"
957
+ ]
958
+ },
959
+ "request_id": {
960
+ "type": "string"
961
+ }
962
+ },
963
+ "required": [
964
+ "data",
965
+ "has_more",
966
+ "next_cursor",
967
+ "request_id"
968
+ ]
969
+ },
892
970
  "SendMessageResponse": {
893
971
  "type": "object",
894
972
  "properties": {
@@ -1841,19 +1919,108 @@
1841
1919
  }
1842
1920
  }
1843
1921
  },
1844
- "/messages": {
1922
+ "/accounts": {
1923
+ "get": {
1924
+ "tags": [
1925
+ "Accounts"
1926
+ ],
1927
+ "summary": "List connected WhatsApp accounts",
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.",
1929
+ "security": [
1930
+ {
1931
+ "bearerAuth": []
1932
+ }
1933
+ ],
1934
+ "parameters": [
1935
+ {
1936
+ "schema": {
1937
+ "type": "string",
1938
+ "enum": [
1939
+ "connected",
1940
+ "all"
1941
+ ]
1942
+ },
1943
+ "required": false,
1944
+ "name": "status",
1945
+ "in": "query"
1946
+ }
1947
+ ],
1948
+ "responses": {
1949
+ "200": {
1950
+ "description": "Account list",
1951
+ "content": {
1952
+ "application/json": {
1953
+ "schema": {
1954
+ "$ref": "#/components/schemas/ListAccountsResponse"
1955
+ }
1956
+ }
1957
+ }
1958
+ },
1959
+ "400": {
1960
+ "description": "Validation failure",
1961
+ "content": {
1962
+ "application/json": {
1963
+ "schema": {
1964
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
1965
+ }
1966
+ }
1967
+ }
1968
+ },
1969
+ "401": {
1970
+ "description": "Authentication failure",
1971
+ "content": {
1972
+ "application/json": {
1973
+ "schema": {
1974
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
1975
+ }
1976
+ }
1977
+ }
1978
+ },
1979
+ "429": {
1980
+ "description": "Rate limit exceeded",
1981
+ "content": {
1982
+ "application/json": {
1983
+ "schema": {
1984
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
1985
+ }
1986
+ }
1987
+ }
1988
+ },
1989
+ "500": {
1990
+ "description": "Internal server error",
1991
+ "content": {
1992
+ "application/json": {
1993
+ "schema": {
1994
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
1995
+ }
1996
+ }
1997
+ }
1998
+ }
1999
+ }
2000
+ }
2001
+ },
2002
+ "/{phone_number_id}/messages": {
1845
2003
  "post": {
1846
2004
  "tags": [
1847
2005
  "Messages"
1848
2006
  ],
1849
2007
  "summary": "Send a WhatsApp message",
1850
- "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.",
1851
2009
  "security": [
1852
2010
  {
1853
2011
  "bearerAuth": []
1854
2012
  }
1855
2013
  ],
1856
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
+ },
1857
2024
  {
1858
2025
  "schema": {
1859
2026
  "type": "string",
@@ -1872,13 +2039,20 @@
1872
2039
  {
1873
2040
  "type": "object",
1874
2041
  "properties": {
1875
- "from": {
2042
+ "messaging_product": {
2043
+ "type": "string",
2044
+ "enum": [
2045
+ "whatsapp"
2046
+ ]
2047
+ },
2048
+ "recipient_type": {
1876
2049
  "type": "string",
1877
- "pattern": "^\\+[1-9]\\d{6,14}$"
2050
+ "enum": [
2051
+ "individual"
2052
+ ]
1878
2053
  },
1879
2054
  "to": {
1880
- "type": "string",
1881
- "pattern": "^\\+[1-9]\\d{6,14}$"
2055
+ "type": "string"
1882
2056
  },
1883
2057
  "type": {
1884
2058
  "type": "string",
@@ -1893,6 +2067,9 @@
1893
2067
  "type": "string",
1894
2068
  "minLength": 1,
1895
2069
  "maxLength": 4096
2070
+ },
2071
+ "preview_url": {
2072
+ "type": "boolean"
1896
2073
  }
1897
2074
  },
1898
2075
  "required": [
@@ -1901,6 +2078,7 @@
1901
2078
  }
1902
2079
  },
1903
2080
  "required": [
2081
+ "messaging_product",
1904
2082
  "to",
1905
2083
  "type",
1906
2084
  "text"
@@ -1909,13 +2087,20 @@
1909
2087
  {
1910
2088
  "type": "object",
1911
2089
  "properties": {
1912
- "from": {
2090
+ "messaging_product": {
2091
+ "type": "string",
2092
+ "enum": [
2093
+ "whatsapp"
2094
+ ]
2095
+ },
2096
+ "recipient_type": {
1913
2097
  "type": "string",
1914
- "pattern": "^\\+[1-9]\\d{6,14}$"
2098
+ "enum": [
2099
+ "individual"
2100
+ ]
1915
2101
  },
1916
2102
  "to": {
1917
- "type": "string",
1918
- "pattern": "^\\+[1-9]\\d{6,14}$"
2103
+ "type": "string"
1919
2104
  },
1920
2105
  "type": {
1921
2106
  "type": "string",
@@ -1926,10 +2111,15 @@
1926
2111
  "image": {
1927
2112
  "type": "object",
1928
2113
  "properties": {
1929
- "url": {
2114
+ "link": {
1930
2115
  "type": "string",
1931
2116
  "format": "uri"
1932
2117
  },
2118
+ "id": {
2119
+ "type": "string",
2120
+ "minLength": 1,
2121
+ "maxLength": 255
2122
+ },
1933
2123
  "caption": {
1934
2124
  "type": "string",
1935
2125
  "maxLength": 1024
@@ -1938,13 +2128,11 @@
1938
2128
  "type": "string",
1939
2129
  "maxLength": 255
1940
2130
  }
1941
- },
1942
- "required": [
1943
- "url"
1944
- ]
2131
+ }
1945
2132
  }
1946
2133
  },
1947
2134
  "required": [
2135
+ "messaging_product",
1948
2136
  "to",
1949
2137
  "type",
1950
2138
  "image"
@@ -1953,13 +2141,20 @@
1953
2141
  {
1954
2142
  "type": "object",
1955
2143
  "properties": {
1956
- "from": {
2144
+ "messaging_product": {
2145
+ "type": "string",
2146
+ "enum": [
2147
+ "whatsapp"
2148
+ ]
2149
+ },
2150
+ "recipient_type": {
1957
2151
  "type": "string",
1958
- "pattern": "^\\+[1-9]\\d{6,14}$"
2152
+ "enum": [
2153
+ "individual"
2154
+ ]
1959
2155
  },
1960
2156
  "to": {
1961
- "type": "string",
1962
- "pattern": "^\\+[1-9]\\d{6,14}$"
2157
+ "type": "string"
1963
2158
  },
1964
2159
  "type": {
1965
2160
  "type": "string",
@@ -1970,10 +2165,15 @@
1970
2165
  "document": {
1971
2166
  "type": "object",
1972
2167
  "properties": {
1973
- "url": {
2168
+ "link": {
1974
2169
  "type": "string",
1975
2170
  "format": "uri"
1976
2171
  },
2172
+ "id": {
2173
+ "type": "string",
2174
+ "minLength": 1,
2175
+ "maxLength": 255
2176
+ },
1977
2177
  "caption": {
1978
2178
  "type": "string",
1979
2179
  "maxLength": 1024
@@ -1982,13 +2182,11 @@
1982
2182
  "type": "string",
1983
2183
  "maxLength": 255
1984
2184
  }
1985
- },
1986
- "required": [
1987
- "url"
1988
- ]
2185
+ }
1989
2186
  }
1990
2187
  },
1991
2188
  "required": [
2189
+ "messaging_product",
1992
2190
  "to",
1993
2191
  "type",
1994
2192
  "document"
@@ -1997,13 +2195,20 @@
1997
2195
  {
1998
2196
  "type": "object",
1999
2197
  "properties": {
2000
- "from": {
2198
+ "messaging_product": {
2001
2199
  "type": "string",
2002
- "pattern": "^\\+[1-9]\\d{6,14}$"
2200
+ "enum": [
2201
+ "whatsapp"
2202
+ ]
2003
2203
  },
2004
- "to": {
2204
+ "recipient_type": {
2005
2205
  "type": "string",
2006
- "pattern": "^\\+[1-9]\\d{6,14}$"
2206
+ "enum": [
2207
+ "individual"
2208
+ ]
2209
+ },
2210
+ "to": {
2211
+ "type": "string"
2007
2212
  },
2008
2213
  "type": {
2009
2214
  "type": "string",
@@ -2014,10 +2219,15 @@
2014
2219
  "video": {
2015
2220
  "type": "object",
2016
2221
  "properties": {
2017
- "url": {
2222
+ "link": {
2018
2223
  "type": "string",
2019
2224
  "format": "uri"
2020
2225
  },
2226
+ "id": {
2227
+ "type": "string",
2228
+ "minLength": 1,
2229
+ "maxLength": 255
2230
+ },
2021
2231
  "caption": {
2022
2232
  "type": "string",
2023
2233
  "maxLength": 1024
@@ -2026,13 +2236,11 @@
2026
2236
  "type": "string",
2027
2237
  "maxLength": 255
2028
2238
  }
2029
- },
2030
- "required": [
2031
- "url"
2032
- ]
2239
+ }
2033
2240
  }
2034
2241
  },
2035
2242
  "required": [
2243
+ "messaging_product",
2036
2244
  "to",
2037
2245
  "type",
2038
2246
  "video"
@@ -2041,13 +2249,20 @@
2041
2249
  {
2042
2250
  "type": "object",
2043
2251
  "properties": {
2044
- "from": {
2252
+ "messaging_product": {
2045
2253
  "type": "string",
2046
- "pattern": "^\\+[1-9]\\d{6,14}$"
2254
+ "enum": [
2255
+ "whatsapp"
2256
+ ]
2047
2257
  },
2048
- "to": {
2258
+ "recipient_type": {
2049
2259
  "type": "string",
2050
- "pattern": "^\\+[1-9]\\d{6,14}$"
2260
+ "enum": [
2261
+ "individual"
2262
+ ]
2263
+ },
2264
+ "to": {
2265
+ "type": "string"
2051
2266
  },
2052
2267
  "type": {
2053
2268
  "type": "string",
@@ -2058,10 +2273,15 @@
2058
2273
  "audio": {
2059
2274
  "type": "object",
2060
2275
  "properties": {
2061
- "url": {
2276
+ "link": {
2062
2277
  "type": "string",
2063
2278
  "format": "uri"
2064
2279
  },
2280
+ "id": {
2281
+ "type": "string",
2282
+ "minLength": 1,
2283
+ "maxLength": 255
2284
+ },
2065
2285
  "caption": {
2066
2286
  "type": "string",
2067
2287
  "maxLength": 1024
@@ -2070,13 +2290,11 @@
2070
2290
  "type": "string",
2071
2291
  "maxLength": 255
2072
2292
  }
2073
- },
2074
- "required": [
2075
- "url"
2076
- ]
2293
+ }
2077
2294
  }
2078
2295
  },
2079
2296
  "required": [
2297
+ "messaging_product",
2080
2298
  "to",
2081
2299
  "type",
2082
2300
  "audio"
@@ -2085,13 +2303,20 @@
2085
2303
  {
2086
2304
  "type": "object",
2087
2305
  "properties": {
2088
- "from": {
2306
+ "messaging_product": {
2089
2307
  "type": "string",
2090
- "pattern": "^\\+[1-9]\\d{6,14}$"
2308
+ "enum": [
2309
+ "whatsapp"
2310
+ ]
2091
2311
  },
2092
- "to": {
2312
+ "recipient_type": {
2093
2313
  "type": "string",
2094
- "pattern": "^\\+[1-9]\\d{6,14}$"
2314
+ "enum": [
2315
+ "individual"
2316
+ ]
2317
+ },
2318
+ "to": {
2319
+ "type": "string"
2095
2320
  },
2096
2321
  "type": {
2097
2322
  "type": "string",
@@ -2107,8 +2332,29 @@
2107
2332
  "minLength": 1
2108
2333
  },
2109
2334
  "language": {
2110
- "type": "string",
2111
- "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
+ ]
2112
2358
  },
2113
2359
  "components": {
2114
2360
  "type": "array",
@@ -2157,6 +2403,7 @@
2157
2403
  }
2158
2404
  },
2159
2405
  "required": [
2406
+ "messaging_product",
2160
2407
  "to",
2161
2408
  "type",
2162
2409
  "template"
@@ -2165,13 +2412,20 @@
2165
2412
  {
2166
2413
  "type": "object",
2167
2414
  "properties": {
2168
- "from": {
2415
+ "messaging_product": {
2416
+ "type": "string",
2417
+ "enum": [
2418
+ "whatsapp"
2419
+ ]
2420
+ },
2421
+ "recipient_type": {
2169
2422
  "type": "string",
2170
- "pattern": "^\\+[1-9]\\d{6,14}$"
2423
+ "enum": [
2424
+ "individual"
2425
+ ]
2171
2426
  },
2172
2427
  "to": {
2173
- "type": "string",
2174
- "pattern": "^\\+[1-9]\\d{6,14}$"
2428
+ "type": "string"
2175
2429
  },
2176
2430
  "type": {
2177
2431
  "type": "string",
@@ -2580,6 +2834,7 @@
2580
2834
  }
2581
2835
  },
2582
2836
  "required": [
2837
+ "messaging_product",
2583
2838
  "to",
2584
2839
  "type",
2585
2840
  "interactive"
@@ -2621,6 +2876,16 @@
2621
2876
  }
2622
2877
  }
2623
2878
  },
2879
+ "404": {
2880
+ "description": "Resource not found",
2881
+ "content": {
2882
+ "application/json": {
2883
+ "schema": {
2884
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
2885
+ }
2886
+ }
2887
+ }
2888
+ },
2624
2889
  "422": {
2625
2890
  "description": "Semantic failure (e.g. idempotency key reuse)",
2626
2891
  "content": {
@@ -2668,13 +2933,22 @@
2668
2933
  "Messages"
2669
2934
  ],
2670
2935
  "summary": "List messages",
2671
- "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.",
2672
2937
  "security": [
2673
2938
  {
2674
2939
  "bearerAuth": []
2675
2940
  }
2676
2941
  ],
2677
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
+ },
2678
2952
  {
2679
2953
  "schema": {
2680
2954
  "type": "string",
@@ -2778,7 +3052,27 @@
2778
3052
  }
2779
3053
  }
2780
3054
  },
2781
- "429": {
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
+ },
3075
+ "429": {
2782
3076
  "description": "Rate limit exceeded",
2783
3077
  "content": {
2784
3078
  "application/json": {
@@ -2801,7 +3095,7 @@
2801
3095
  }
2802
3096
  }
2803
3097
  },
2804
- "/messages/{id}": {
3098
+ "/{phone_number_id}/messages/{id}": {
2805
3099
  "get": {
2806
3100
  "tags": [
2807
3101
  "Messages"
@@ -2813,6 +3107,15 @@
2813
3107
  }
2814
3108
  ],
2815
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
+ },
2816
3119
  {
2817
3120
  "schema": {
2818
3121
  "type": "string",
@@ -2864,6 +3167,16 @@
2864
3167
  }
2865
3168
  }
2866
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
+ },
2867
3180
  "429": {
2868
3181
  "description": "Rate limit exceeded",
2869
3182
  "content": {
@@ -2887,19 +3200,28 @@
2887
3200
  }
2888
3201
  }
2889
3202
  },
2890
- "/templates": {
3203
+ "/{phone_number_id}/templates": {
2891
3204
  "get": {
2892
3205
  "tags": [
2893
3206
  "Templates"
2894
3207
  ],
2895
3208
  "summary": "List approved templates",
2896
- "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`.",
2897
3210
  "security": [
2898
3211
  {
2899
3212
  "bearerAuth": []
2900
3213
  }
2901
3214
  ],
2902
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
+ },
2903
3225
  {
2904
3226
  "schema": {
2905
3227
  "type": "string",
@@ -2974,6 +3296,26 @@
2974
3296
  }
2975
3297
  }
2976
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
+ },
2977
3319
  "429": {
2978
3320
  "description": "Rate limit exceeded",
2979
3321
  "content": {
@@ -2997,7 +3339,7 @@
2997
3339
  }
2998
3340
  }
2999
3341
  },
3000
- "/templates/{name}": {
3342
+ "/{phone_number_id}/templates/{name}": {
3001
3343
  "get": {
3002
3344
  "tags": [
3003
3345
  "Templates"
@@ -3009,6 +3351,15 @@
3009
3351
  }
3010
3352
  ],
3011
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
+ },
3012
3363
  {
3013
3364
  "schema": {
3014
3365
  "type": "string",
@@ -3071,6 +3422,16 @@
3071
3422
  }
3072
3423
  }
3073
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
+ },
3074
3435
  "429": {
3075
3436
  "description": "Rate limit exceeded",
3076
3437
  "content": {
@@ -4274,19 +4635,28 @@
4274
4635
  }
4275
4636
  }
4276
4637
  },
4277
- "/conversations": {
4638
+ "/{phone_number_id}/conversations": {
4278
4639
  "get": {
4279
4640
  "tags": [
4280
4641
  "Conversations"
4281
4642
  ],
4282
4643
  "summary": "List conversations",
4283
- "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).",
4284
4645
  "security": [
4285
4646
  {
4286
4647
  "bearerAuth": []
4287
4648
  }
4288
4649
  ],
4289
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
+ },
4290
4660
  {
4291
4661
  "schema": {
4292
4662
  "type": "string",
@@ -4358,6 +4728,26 @@
4358
4728
  }
4359
4729
  }
4360
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
+ },
4361
4751
  "429": {
4362
4752
  "description": "Rate limit exceeded",
4363
4753
  "content": {
@@ -4381,7 +4771,7 @@
4381
4771
  }
4382
4772
  }
4383
4773
  },
4384
- "/conversations/{id}": {
4774
+ "/{phone_number_id}/conversations/{id}": {
4385
4775
  "get": {
4386
4776
  "tags": [
4387
4777
  "Conversations"
@@ -4393,6 +4783,15 @@
4393
4783
  }
4394
4784
  ],
4395
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
+ },
4396
4795
  {
4397
4796
  "schema": {
4398
4797
  "type": "string",
@@ -4444,6 +4843,16 @@
4444
4843
  }
4445
4844
  }
4446
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
+ },
4447
4856
  "429": {
4448
4857
  "description": "Rate limit exceeded",
4449
4858
  "content": {
@@ -4478,6 +4887,15 @@
4478
4887
  }
4479
4888
  ],
4480
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
+ },
4481
4899
  {
4482
4900
  "schema": {
4483
4901
  "type": "string",
@@ -4556,6 +4974,16 @@
4556
4974
  }
4557
4975
  }
4558
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
+ },
4559
4987
  "429": {
4560
4988
  "description": "Rate limit exceeded",
4561
4989
  "content": {
@@ -4579,19 +5007,28 @@
4579
5007
  }
4580
5008
  }
4581
5009
  },
4582
- "/contacts": {
5010
+ "/{phone_number_id}/contacts": {
4583
5011
  "get": {
4584
5012
  "tags": [
4585
5013
  "Contacts"
4586
5014
  ],
4587
5015
  "summary": "List contacts",
4588
- "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).",
4589
5017
  "security": [
4590
5018
  {
4591
5019
  "bearerAuth": []
4592
5020
  }
4593
5021
  ],
4594
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
+ },
4595
5032
  {
4596
5033
  "schema": {
4597
5034
  "type": "string",
@@ -4660,6 +5097,26 @@
4660
5097
  }
4661
5098
  }
4662
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
+ },
4663
5120
  "429": {
4664
5121
  "description": "Rate limit exceeded",
4665
5122
  "content": {
@@ -4687,22 +5144,29 @@
4687
5144
  "Contacts"
4688
5145
  ],
4689
5146
  "summary": "Create a contact",
4690
- "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.",
4691
5148
  "security": [
4692
5149
  {
4693
5150
  "bearerAuth": []
4694
5151
  }
4695
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
+ ],
4696
5164
  "requestBody": {
4697
5165
  "content": {
4698
5166
  "application/json": {
4699
5167
  "schema": {
4700
5168
  "type": "object",
4701
5169
  "properties": {
4702
- "from": {
4703
- "type": "string",
4704
- "pattern": "^\\+[1-9]\\d{6,14}$"
4705
- },
4706
5170
  "phone_number": {
4707
5171
  "type": "string",
4708
5172
  "pattern": "^\\+[1-9]\\d{6,14}$"
@@ -4763,6 +5227,16 @@
4763
5227
  }
4764
5228
  }
4765
5229
  },
5230
+ "404": {
5231
+ "description": "Resource not found",
5232
+ "content": {
5233
+ "application/json": {
5234
+ "schema": {
5235
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
5236
+ }
5237
+ }
5238
+ }
5239
+ },
4766
5240
  "422": {
4767
5241
  "description": "Semantic failure (e.g. idempotency key reuse)",
4768
5242
  "content": {
@@ -4796,7 +5270,7 @@
4796
5270
  }
4797
5271
  }
4798
5272
  },
4799
- "/contacts/{id}": {
5273
+ "/{phone_number_id}/contacts/{id}": {
4800
5274
  "get": {
4801
5275
  "tags": [
4802
5276
  "Contacts"
@@ -4808,6 +5282,15 @@
4808
5282
  }
4809
5283
  ],
4810
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
+ },
4811
5294
  {
4812
5295
  "schema": {
4813
5296
  "type": "string",
@@ -4859,6 +5342,16 @@
4859
5342
  }
4860
5343
  }
4861
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
+ },
4862
5355
  "429": {
4863
5356
  "description": "Rate limit exceeded",
4864
5357
  "content": {
@@ -4893,6 +5386,15 @@
4893
5386
  }
4894
5387
  ],
4895
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
+ },
4896
5398
  {
4897
5399
  "schema": {
4898
5400
  "type": "string",
@@ -4988,6 +5490,16 @@
4988
5490
  }
4989
5491
  }
4990
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
+ },
4991
5503
  "429": {
4992
5504
  "description": "Rate limit exceeded",
4993
5505
  "content": {
@@ -5022,6 +5534,15 @@
5022
5534
  }
5023
5535
  ],
5024
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
+ },
5025
5546
  {
5026
5547
  "schema": {
5027
5548
  "type": "string",
@@ -5073,6 +5594,16 @@
5073
5594
  }
5074
5595
  }
5075
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
+ },
5076
5607
  "429": {
5077
5608
  "description": "Rate limit exceeded",
5078
5609
  "content": {
@@ -5096,7 +5627,7 @@
5096
5627
  }
5097
5628
  }
5098
5629
  },
5099
- "/messages/{id}/media": {
5630
+ "/{phone_number_id}/messages/{id}/media": {
5100
5631
  "get": {
5101
5632
  "tags": [
5102
5633
  "Messages"
@@ -5109,6 +5640,15 @@
5109
5640
  }
5110
5641
  ],
5111
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
+ },
5112
5652
  {
5113
5653
  "schema": {
5114
5654
  "type": "string",
@@ -5161,6 +5701,16 @@
5161
5701
  }
5162
5702
  }
5163
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
+ },
5164
5714
  "429": {
5165
5715
  "description": "Rate limit exceeded",
5166
5716
  "content": {
@@ -5184,7 +5734,7 @@
5184
5734
  }
5185
5735
  }
5186
5736
  },
5187
- "/contacts/{id}/labels": {
5737
+ "/{phone_number_id}/contacts/{id}/labels": {
5188
5738
  "post": {
5189
5739
  "tags": [
5190
5740
  "Contacts"
@@ -5197,6 +5747,15 @@
5197
5747
  }
5198
5748
  ],
5199
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
+ },
5200
5759
  {
5201
5760
  "schema": {
5202
5761
  "type": "string",
@@ -5266,6 +5825,16 @@
5266
5825
  }
5267
5826
  }
5268
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
+ },
5269
5838
  "429": {
5270
5839
  "description": "Rate limit exceeded",
5271
5840
  "content": {
@@ -5289,7 +5858,7 @@
5289
5858
  }
5290
5859
  }
5291
5860
  },
5292
- "/contacts/{id}/labels/{label_id}": {
5861
+ "/{phone_number_id}/contacts/{id}/labels/{label_id}": {
5293
5862
  "delete": {
5294
5863
  "tags": [
5295
5864
  "Contacts"
@@ -5301,6 +5870,15 @@
5301
5870
  }
5302
5871
  ],
5303
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
+ },
5304
5882
  {
5305
5883
  "schema": {
5306
5884
  "type": "string",
@@ -5361,6 +5939,16 @@
5361
5939
  }
5362
5940
  }
5363
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
+ },
5364
5952
  "429": {
5365
5953
  "description": "Rate limit exceeded",
5366
5954
  "content": {
@@ -5384,18 +5972,29 @@
5384
5972
  }
5385
5973
  }
5386
5974
  },
5387
- "/contacts/bulk_label": {
5975
+ "/{phone_number_id}/contacts/bulk_label": {
5388
5976
  "post": {
5389
5977
  "tags": [
5390
5978
  "Contacts"
5391
5979
  ],
5392
5980
  "summary": "Attach or detach a label across many contacts",
5393
- "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`.",
5394
5982
  "security": [
5395
5983
  {
5396
5984
  "bearerAuth": []
5397
5985
  }
5398
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
+ ],
5399
5998
  "requestBody": {
5400
5999
  "content": {
5401
6000
  "application/json": {
@@ -5473,6 +6072,16 @@
5473
6072
  }
5474
6073
  }
5475
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
+ },
5476
6085
  "429": {
5477
6086
  "description": "Rate limit exceeded",
5478
6087
  "content": {
@@ -5496,7 +6105,7 @@
5496
6105
  }
5497
6106
  }
5498
6107
  },
5499
- "/conversations/{id}/labels": {
6108
+ "/{phone_number_id}/conversations/{id}/labels": {
5500
6109
  "post": {
5501
6110
  "tags": [
5502
6111
  "Conversations"
@@ -5508,6 +6117,15 @@
5508
6117
  }
5509
6118
  ],
5510
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
+ },
5511
6129
  {
5512
6130
  "schema": {
5513
6131
  "type": "string",
@@ -5577,6 +6195,16 @@
5577
6195
  }
5578
6196
  }
5579
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
+ },
5580
6208
  "429": {
5581
6209
  "description": "Rate limit exceeded",
5582
6210
  "content": {
@@ -5600,7 +6228,7 @@
5600
6228
  }
5601
6229
  }
5602
6230
  },
5603
- "/conversations/{id}/labels/{label_id}": {
6231
+ "/{phone_number_id}/conversations/{id}/labels/{label_id}": {
5604
6232
  "delete": {
5605
6233
  "tags": [
5606
6234
  "Conversations"
@@ -5612,6 +6240,15 @@
5612
6240
  }
5613
6241
  ],
5614
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
+ },
5615
6252
  {
5616
6253
  "schema": {
5617
6254
  "type": "string",
@@ -5672,6 +6309,16 @@
5672
6309
  }
5673
6310
  }
5674
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
+ },
5675
6322
  "429": {
5676
6323
  "description": "Rate limit exceeded",
5677
6324
  "content": {