@first-to-fly/crm-sdk 1.11.0 → 1.12.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.
package/README.md CHANGED
@@ -281,6 +281,9 @@ const crm = createCrmApiClient({
281
281
  const { items } = await crm.contacts.list({ page: 1, pageSize: 25 });
282
282
  ```
283
283
 
284
+ If you build your own chat screen, read each conversation's `send_policy` to know
285
+ whether a reply may be sent. See [Can a reply be sent?](#can-a-reply-be-sent-send_policy).
286
+
284
287
  #### Environment checklist
285
288
 
286
289
  | Where | Variable | Notes |
@@ -1059,6 +1062,69 @@ try {
1059
1062
  }
1060
1063
  ```
1061
1064
 
1065
+ ### Can a reply be sent? `send_policy`
1066
+
1067
+ Every conversation the CRM returns (`crm.conversations.list`, `.get`, and the
1068
+ other conversation responses) carries `send_policy`. It says what may be sent in
1069
+ that conversation right now. The CRM builds it from the rules its send check
1070
+ enforces for the window, consent and blocking (the window and consent parts are
1071
+ the same code), so you do not have to copy those rules into your app.
1072
+
1073
+ | Field | Meaning |
1074
+ |---|---|
1075
+ | `free_text` | `'open'` when a normal reply may be sent now, else `'closed'`. |
1076
+ | `window` | `'24h'` when replies are only allowed for 24 hours after the contact's last message on this channel. `'none'` when there is no time limit. |
1077
+ | `closes_at` | When the 24-hour window closes (ISO time). It stays set, in the past, after the window has closed. `null` when `window` is `'none'` or the contact has not messaged yet. |
1078
+ | `reason` | Why `free_text` is `'closed'`: `blocked` (contact or conversation is blocked), `suppressed` (email only: the contact's address is on the workspace's Do Not Email list), `opted_out` (contact opted out of WhatsApp), `consent_required` (contact has not opted in to WhatsApp and is outside the 24 hours), `window_closed`, `no_inbound_message` (the contact has never messaged on this channel), `not_supported` (SMS and voice have no reply). `null` when open. |
1079
+ | `template` | `true` when an approved WhatsApp template may be sent. Only official WhatsApp has templates. |
1080
+ | `template_reason` | Set when WhatsApp consent is the only thing stopping a template: `consent_required` or `opted_out`. Otherwise `null`. |
1081
+ | `human_agent` | Messenger only. `available`: the 24 hours have passed and the contact messaged within 7 days, so a reply with the Human Agent tag is allowed. `enabled`: the conversation's Human Agent switch is on and `available` is true. `expires_at`: the contact's last message plus 7 days. Human Agent never makes `free_text` `'open'`: the send must carry `tag: 'HUMAN_AGENT'` and `messaging_type: 'MESSAGE_TAG'`. |
1082
+
1083
+ How to use it:
1084
+
1085
+ - Show a reply box when `free_text` is `'open'`.
1086
+ - Offer a template when `template` is `true`.
1087
+ - Show `closes_at` as the time replies close. If it has passed while your screen
1088
+ was open, treat the conversation as closed and read it again.
1089
+ - When `free_text` is `'closed'`, use `reason` to tell the user why.
1090
+ - Do not work the window out yourself from `metadata.is_within_24h_window` or
1091
+ `channel_info.channel_windows`. Those fields stay for older clients;
1092
+ `is_within_24h_window` is true when any channel is inside its window, not the
1093
+ one being replied on.
1094
+
1095
+ ```typescript
1096
+ const conversation = await crm.conversations.get(conversationId);
1097
+ const { free_text, closes_at, reason, template } = conversation.send_policy;
1098
+
1099
+ if (free_text === 'open') {
1100
+ // show the reply box; if closes_at is set, replies close at that time
1101
+ } else if (template) {
1102
+ // WhatsApp outside the 24 hours: only a template can be sent
1103
+ } else {
1104
+ // no reply possible: explain with `reason`
1105
+ }
1106
+ ```
1107
+
1108
+ Channels with no time limit: email, WhatsApp Web, web chat, Telegram, website
1109
+ forms and the partner app channel. Official WhatsApp, Messenger and Instagram
1110
+ have the 24-hour window.
1111
+
1112
+ In a product-managed workspace, WhatsApp consent also applies on official
1113
+ WhatsApp and WhatsApp Web (WhatsApp Web groups are exempt). A contact who opted
1114
+ out gets nothing. A contact who has not opted in can be answered with free text
1115
+ for 24 hours after their last message, and cannot be sent a template; on
1116
+ WhatsApp Web this is the one case where `window` is `'24h'`.
1117
+
1118
+ The policy describes the conversation on its own channel (`metadata.channel`).
1119
+ For a merged conversation that is the channel of the conversation you read, not
1120
+ of the other conversations merged into it.
1121
+
1122
+ The server still checks every send, and it checks more than the policy states:
1123
+ the channel may be disconnected, the contact may have no address on that channel,
1124
+ or the window may have closed since you read the policy. So a send can still be
1125
+ refused when the policy said open. Handle the error from `messages.send` as
1126
+ before.
1127
+
1062
1128
  ### Server-to-server with an API key
1063
1129
 
1064
1130
  For machine-to-machine calls you can pass an `X-API-Key` instead of a bearer:
package/dist/api.d.cts CHANGED
@@ -1,5 +1,5 @@
1
- import { C as ContactQuery, a as ContactList, b as Contact, c as ContactCreate, d as ContactUpdate, L as LeadQuery, e as ListEnvelope, f as Lead, g as LeadCreate, h as LeadUpdate, T as TaskQuery, i as Task, j as LegacyTaskUpdate, k as LegacyTask, P as ProductQuery, l as Product, m as ProductCreate, n as ProductUpdate, o as ConversationQuery, p as Conversation, q as ConversationUpdate, M as MessageQuery, r as Message, s as MessageCreate, t as TagQuery, u as TagWithUsage, v as TagCreate, w as Tag } from './crm-contracts-BeC2pzgj.cjs';
2
- export { x as ContactChanges, y as ContactChangesQuery, z as ContactRefUpsertBody, A as ContactRefUpsertResult, B as LeadCapture, D as LeadNote, E as LeadNoteCreate, F as PartnerContactEraseByIdentityBody, G as PartnerContactEraseByIdentityResult, H as PartnerContactEraseResult, I as PartnerInboundMessageBody, J as PartnerInboundMessageResult, K as PartnerMessageChange, N as PartnerMessageChanges, O as PartnerMessageChangesQuery, Q as PartnerThreadDeleteResult, R as PartnerWebhookCreated, S as PartnerWebhookGet, U as PartnerWebhookPutBody, V as PartnerWebhookRotate, W as PartnerWebhookUpdated, X as PartnerWorkspaceCreated, Y as PartnerWorkspaceDetail, Z as PartnerWorkspaceExisting, _ as PartnerWorkspacePatchBody, $ as PartnerWorkspaceSecret, a0 as PartnerWorkspaceStatus, a1 as PartnerWorkspaceUpsertBody, a2 as PartnerWorkspaceUsage, a3 as PartnerWorkspaceUsageQuery, a4 as TagList } from './crm-contracts-BeC2pzgj.cjs';
1
+ import { C as ContactQuery, a as ContactList, b as Contact, c as ContactCreate, d as ContactUpdate, L as LeadQuery, e as ListEnvelope, f as Lead, g as LeadCreate, h as LeadUpdate, T as TaskQuery, i as Task, j as LegacyTaskUpdate, k as LegacyTask, P as ProductQuery, l as Product, m as ProductCreate, n as ProductUpdate, o as ConversationQuery, p as Conversation, q as ConversationUpdate, M as MessageQuery, r as Message, s as MessageCreate, t as TagQuery, u as TagWithUsage, v as TagCreate, w as Tag } from './crm-contracts-Cezh6uNS.cjs';
2
+ export { x as ContactChanges, y as ContactChangesQuery, z as ContactRefUpsertBody, A as ContactRefUpsertResult, B as LeadCapture, D as LeadNote, E as LeadNoteCreate, F as PartnerContactEraseByIdentityBody, G as PartnerContactEraseByIdentityResult, H as PartnerContactEraseResult, I as PartnerInboundMessageBody, J as PartnerInboundMessageResult, K as PartnerMessageChange, N as PartnerMessageChanges, O as PartnerMessageChangesQuery, Q as PartnerThreadDeleteResult, R as PartnerWebhookCreated, S as PartnerWebhookGet, U as PartnerWebhookPutBody, V as PartnerWebhookRotate, W as PartnerWebhookUpdated, X as PartnerWorkspaceCreated, Y as PartnerWorkspaceDetail, Z as PartnerWorkspaceExisting, _ as PartnerWorkspacePatchBody, $ as PartnerWorkspaceSecret, a0 as PartnerWorkspaceStatus, a1 as PartnerWorkspaceUpsertBody, a2 as PartnerWorkspaceUsage, a3 as PartnerWorkspaceUsageQuery, a4 as TagList } from './crm-contracts-Cezh6uNS.cjs';
3
3
 
4
4
  /**
5
5
  * Typed CRM REST API client for SaaS backends.
package/dist/api.d.ts CHANGED
@@ -1,5 +1,5 @@
1
- import { C as ContactQuery, a as ContactList, b as Contact, c as ContactCreate, d as ContactUpdate, L as LeadQuery, e as ListEnvelope, f as Lead, g as LeadCreate, h as LeadUpdate, T as TaskQuery, i as Task, j as LegacyTaskUpdate, k as LegacyTask, P as ProductQuery, l as Product, m as ProductCreate, n as ProductUpdate, o as ConversationQuery, p as Conversation, q as ConversationUpdate, M as MessageQuery, r as Message, s as MessageCreate, t as TagQuery, u as TagWithUsage, v as TagCreate, w as Tag } from './crm-contracts-BeC2pzgj.js';
2
- export { x as ContactChanges, y as ContactChangesQuery, z as ContactRefUpsertBody, A as ContactRefUpsertResult, B as LeadCapture, D as LeadNote, E as LeadNoteCreate, F as PartnerContactEraseByIdentityBody, G as PartnerContactEraseByIdentityResult, H as PartnerContactEraseResult, I as PartnerInboundMessageBody, J as PartnerInboundMessageResult, K as PartnerMessageChange, N as PartnerMessageChanges, O as PartnerMessageChangesQuery, Q as PartnerThreadDeleteResult, R as PartnerWebhookCreated, S as PartnerWebhookGet, U as PartnerWebhookPutBody, V as PartnerWebhookRotate, W as PartnerWebhookUpdated, X as PartnerWorkspaceCreated, Y as PartnerWorkspaceDetail, Z as PartnerWorkspaceExisting, _ as PartnerWorkspacePatchBody, $ as PartnerWorkspaceSecret, a0 as PartnerWorkspaceStatus, a1 as PartnerWorkspaceUpsertBody, a2 as PartnerWorkspaceUsage, a3 as PartnerWorkspaceUsageQuery, a4 as TagList } from './crm-contracts-BeC2pzgj.js';
1
+ import { C as ContactQuery, a as ContactList, b as Contact, c as ContactCreate, d as ContactUpdate, L as LeadQuery, e as ListEnvelope, f as Lead, g as LeadCreate, h as LeadUpdate, T as TaskQuery, i as Task, j as LegacyTaskUpdate, k as LegacyTask, P as ProductQuery, l as Product, m as ProductCreate, n as ProductUpdate, o as ConversationQuery, p as Conversation, q as ConversationUpdate, M as MessageQuery, r as Message, s as MessageCreate, t as TagQuery, u as TagWithUsage, v as TagCreate, w as Tag } from './crm-contracts-Cezh6uNS.js';
2
+ export { x as ContactChanges, y as ContactChangesQuery, z as ContactRefUpsertBody, A as ContactRefUpsertResult, B as LeadCapture, D as LeadNote, E as LeadNoteCreate, F as PartnerContactEraseByIdentityBody, G as PartnerContactEraseByIdentityResult, H as PartnerContactEraseResult, I as PartnerInboundMessageBody, J as PartnerInboundMessageResult, K as PartnerMessageChange, N as PartnerMessageChanges, O as PartnerMessageChangesQuery, Q as PartnerThreadDeleteResult, R as PartnerWebhookCreated, S as PartnerWebhookGet, U as PartnerWebhookPutBody, V as PartnerWebhookRotate, W as PartnerWebhookUpdated, X as PartnerWorkspaceCreated, Y as PartnerWorkspaceDetail, Z as PartnerWorkspaceExisting, _ as PartnerWorkspacePatchBody, $ as PartnerWorkspaceSecret, a0 as PartnerWorkspaceStatus, a1 as PartnerWorkspaceUpsertBody, a2 as PartnerWorkspaceUsage, a3 as PartnerWorkspaceUsageQuery, a4 as TagList } from './crm-contracts-Cezh6uNS.js';
3
3
 
4
4
  /**
5
5
  * Typed CRM REST API client for SaaS backends.
@@ -928,6 +928,10 @@ type Conversation = {
928
928
  direction?: ("inbound" | "outbound") | undefined;
929
929
  status?: ("sent" | "delivered" | "read" | "failed") | undefined;
930
930
  };
931
+ owning_team: {
932
+ id: string;
933
+ name: string | null;
934
+ } | null;
931
935
  assignment: {
932
936
  assigned_to?: string | undefined;
933
937
  assigned_user_name?: string | undefined;
@@ -958,6 +962,19 @@ type Conversation = {
958
962
  is_enabled: boolean;
959
963
  activated_at: string | null;
960
964
  };
965
+ send_policy: {
966
+ free_text: "open" | "closed";
967
+ window: "none" | "24h";
968
+ closes_at: string | null;
969
+ reason: ("blocked" | "suppressed" | "opted_out" | "consent_required" | "window_closed" | "no_inbound_message" | "not_supported") | null;
970
+ template: boolean;
971
+ template_reason: ("consent_required" | "opted_out") | null;
972
+ human_agent: {
973
+ available: boolean;
974
+ enabled: boolean;
975
+ expires_at: string | null;
976
+ };
977
+ };
961
978
  ai_handoff_state: {
962
979
  needs_human_reply: boolean;
963
980
  reason: string | null;
@@ -928,6 +928,10 @@ type Conversation = {
928
928
  direction?: ("inbound" | "outbound") | undefined;
929
929
  status?: ("sent" | "delivered" | "read" | "failed") | undefined;
930
930
  };
931
+ owning_team: {
932
+ id: string;
933
+ name: string | null;
934
+ } | null;
931
935
  assignment: {
932
936
  assigned_to?: string | undefined;
933
937
  assigned_user_name?: string | undefined;
@@ -958,6 +962,19 @@ type Conversation = {
958
962
  is_enabled: boolean;
959
963
  activated_at: string | null;
960
964
  };
965
+ send_policy: {
966
+ free_text: "open" | "closed";
967
+ window: "none" | "24h";
968
+ closes_at: string | null;
969
+ reason: ("blocked" | "suppressed" | "opted_out" | "consent_required" | "window_closed" | "no_inbound_message" | "not_supported") | null;
970
+ template: boolean;
971
+ template_reason: ("consent_required" | "opted_out") | null;
972
+ human_agent: {
973
+ available: boolean;
974
+ enabled: boolean;
975
+ expires_at: string | null;
976
+ };
977
+ };
961
978
  ai_handoff_state: {
962
979
  needs_human_reply: boolean;
963
980
  reason: string | null;
@@ -1,5 +1,5 @@
1
- import { a1 as PartnerWorkspaceUpsertBody$1, Y as PartnerWorkspaceDetail$1, _ as PartnerWorkspacePatchBody$1, a2 as PartnerWorkspaceUsage, z as ContactRefUpsertBody, A as ContactRefUpsertResult, H as PartnerContactEraseResult, F as PartnerContactEraseByIdentityBody, G as PartnerContactEraseByIdentityResult, x as ContactChanges } from './crm-contracts-BeC2pzgj.cjs';
2
- export { y as ContactChangesQuery } from './crm-contracts-BeC2pzgj.cjs';
1
+ import { a1 as PartnerWorkspaceUpsertBody$1, Y as PartnerWorkspaceDetail$1, _ as PartnerWorkspacePatchBody$1, a2 as PartnerWorkspaceUsage, z as ContactRefUpsertBody, A as ContactRefUpsertResult, H as PartnerContactEraseResult, F as PartnerContactEraseByIdentityBody, G as PartnerContactEraseByIdentityResult, x as ContactChanges } from './crm-contracts-Cezh6uNS.cjs';
2
+ export { y as ContactChangesQuery } from './crm-contracts-Cezh6uNS.cjs';
3
3
 
4
4
  /**
5
5
  * Internal HTTP helper for the server-side `partner` entry point. Not part of the
package/dist/partner.d.ts CHANGED
@@ -1,5 +1,5 @@
1
- import { a1 as PartnerWorkspaceUpsertBody$1, Y as PartnerWorkspaceDetail$1, _ as PartnerWorkspacePatchBody$1, a2 as PartnerWorkspaceUsage, z as ContactRefUpsertBody, A as ContactRefUpsertResult, H as PartnerContactEraseResult, F as PartnerContactEraseByIdentityBody, G as PartnerContactEraseByIdentityResult, x as ContactChanges } from './crm-contracts-BeC2pzgj.js';
2
- export { y as ContactChangesQuery } from './crm-contracts-BeC2pzgj.js';
1
+ import { a1 as PartnerWorkspaceUpsertBody$1, Y as PartnerWorkspaceDetail$1, _ as PartnerWorkspacePatchBody$1, a2 as PartnerWorkspaceUsage, z as ContactRefUpsertBody, A as ContactRefUpsertResult, H as PartnerContactEraseResult, F as PartnerContactEraseByIdentityBody, G as PartnerContactEraseByIdentityResult, x as ContactChanges } from './crm-contracts-Cezh6uNS.js';
2
+ export { y as ContactChangesQuery } from './crm-contracts-Cezh6uNS.js';
3
3
 
4
4
  /**
5
5
  * Internal HTTP helper for the server-side `partner` entry point. Not part of the
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@first-to-fly/crm-sdk",
3
- "version": "1.11.0",
3
+ "version": "1.12.0",
4
4
  "repository": {
5
5
  "type": "git",
6
6
  "url": "git+https://github.com/first-to-fly/crm.git",