@signalhousellc/sdk 1.0.56 → 1.0.62

package/src/domains/Messages.js

@@ -247,6 +247,16 @@ export class Messages {
 
 	/**
 	 * Send an SMS message to one or more recipient phone numbers
+	 *
+	 * The response reports the send outcome with three fields so callers do not have to inspect
+	 * insertedMessages: requestedRecipientCount, enqueuedCount, and failedCount. enqueuedCount is the
+	 * number of recipients accepted for delivery and is 0 when the send was fully blocked (by the
+	 * moderation filter or a campaign opt-out); the request still resolves successfully in that case, so
+	 * treat enqueuedCount, not the HTTP status, as the signal that a message was accepted. Blocked
+	 * recipients are returned in insertedMessages with status "FAILED"; recipients on the global Do Not
+	 * Contact list are reported in dncBlockedNumbers with no message record. Each FAILED message carries
+	 * errorCode, a stable machine-readable cause (campaign opt-out is "OUT"; null on success or on
+	 * failures with no assigned code) that is also included on the FAILED status-callback payload.
 	 * @async
 	 * @roles api, admin, developer, billing, user
 	 * @param {Object} params - The parameters for sending an SMS message
@@ -276,16 +286,22 @@ export class Messages {
 	 * @param {string[]} params.recipientPhoneNumbers - The phone number(s) to send the message to
 	 * @param {string} params.messageBody - The body of the P2P message
 	 * @param {string} [params.statusCallbackUrl] - The URL to receive status callbacks
+	 * @param {string} [params.groupId] - Explicit group to send from. Defaults to the group in your auth context.
+	 * @param {string} [params.subgroupId] - Explicit subgroup to attribute the send (and its inbound reply) to.
+	 *   P2P has no dedicated sender number, so pass this to record the send against a specific subgroup; it also
+	 *   resolves the group. Defaults to the group's oldest subgroup.
 	 * @param {boolean} [params.useSignalHouseShortlinks] - When false, SignalHouse applies no link-shortening
 	 *   or text-spin and your pre-spun links/content are sent verbatim (bring-your-own spinner). Defaults to
 	 *   true server-side (the SignalHouse shortlink system, which mints unique per-recipient links).
 	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
 	 * @returns {Promise<Object>} - A promise that resolves to the response data from the server
 	 */
-	async sendP2P({ recipientPhoneNumbers, messageBody, statusCallbackUrl, useSignalHouseShortlinks, options = {} }) {
+	async sendP2P({ recipientPhoneNumbers, messageBody, statusCallbackUrl, groupId, subgroupId, useSignalHouseShortlinks, options = {} }) {
 		this.client._require({ recipientPhoneNumbers, messageBody });
 		const body = { recipientPhoneNumber: recipientPhoneNumbers, messageBody };
 		if (statusCallbackUrl) body.statusCallbackUrl = statusCallbackUrl;
+		if (groupId) body.groupId = groupId;
+		if (subgroupId) body.subgroupId = subgroupId;
 		if (typeof useSignalHouseShortlinks === "boolean") body.useSignalHouseShortlinks = useSignalHouseShortlinks;
 		return this.client(`/message/p2p`, {
 			method: "POST",
@@ -312,6 +328,16 @@ export class Messages {
 
 	/**
 	 * Send an MMS message to one or more recipient phone numbers, with optional media attachments and status callback
+	 *
+	 * The response reports the send outcome with three fields so callers do not have to inspect
+	 * insertedMessages: requestedRecipientCount, enqueuedCount, and failedCount. enqueuedCount is the
+	 * number of recipients accepted for delivery and is 0 when the send was fully blocked (by the
+	 * moderation filter or a campaign opt-out); the request still resolves successfully in that case, so
+	 * treat enqueuedCount, not the HTTP status, as the signal that a message was accepted. Blocked
+	 * recipients are returned in insertedMessages with status "FAILED"; recipients on the global Do Not
+	 * Contact list are reported in dncBlockedNumbers with no message record. Each FAILED message carries
+	 * errorCode, a stable machine-readable cause (campaign opt-out is "OUT"; null on success or on
+	 * failures with no assigned code) that is also included on the FAILED status-callback payload.
 	 * @async
 	 * @roles api, admin, developer, billing, user
 	 * @param {Object} params - The parameters for sending an MMS message
@@ -371,6 +397,16 @@ export class Messages {
 
 	/**
 	 * Send a group MMS message to one or more recipient phone numbers, with optional media attachments and status callback
+	 *
+	 * The response reports the send outcome with three fields so callers do not have to inspect
+	 * insertedMessages: requestedRecipientCount, enqueuedCount, and failedCount. enqueuedCount is the
+	 * number of recipients accepted for delivery and is 0 when the send was fully blocked (by the
+	 * moderation filter or a campaign opt-out); the request still resolves successfully in that case, so
+	 * treat enqueuedCount, not the HTTP status, as the signal that a message was accepted. Blocked
+	 * recipients are returned in insertedMessages with status "FAILED"; recipients on the global Do Not
+	 * Contact list are reported in dncBlockedNumbers with no message record. Each FAILED message carries
+	 * errorCode, a stable machine-readable cause (campaign opt-out is "OUT"; null on success or on
+	 * failures with no assigned code) that is also included on the FAILED status-callback payload.
 	 * @async
 	 * @roles api, admin, developer, billing, user
 	 * @param {Object} params - The parameters for sending an MMS message