@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 +66 -0
- package/dist/api.d.cts +2 -2
- package/dist/api.d.ts +2 -2
- package/dist/{crm-contracts-BeC2pzgj.d.cts → crm-contracts-Cezh6uNS.d.cts} +17 -0
- package/dist/{crm-contracts-BeC2pzgj.d.ts → crm-contracts-Cezh6uNS.d.ts} +17 -0
- package/dist/partner.d.cts +2 -2
- package/dist/partner.d.ts +2 -2
- package/package.json +1 -1
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-
|
|
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-
|
|
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-
|
|
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-
|
|
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;
|
package/dist/partner.d.cts
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-
|
|
2
|
-
export { y as ContactChangesQuery } from './crm-contracts-
|
|
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-
|
|
2
|
-
export { y as ContactChangesQuery } from './crm-contracts-
|
|
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
|