> ## Documentation Index
> Fetch the complete documentation index at: https://developers.redo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# commerceAgentConfigPublish

> Publish the Playbook settings you pass, not the rest of the draft: a copy of the published version with these values becomes the new `PUBLISHED` version. The values are also written into the shared draft, the one the Playbook page edits, so the merchant's next Save & Publish keeps them; so is extended outreach when turning the agent on switches it on. The draft's other pending edits stay pending, except a value paired with one you pass (escalation and its support email, or the two late-return cutoffs) when the draft's would no longer be valid with yours. A draft left equal to the published version is deleted. There is no revision check: the latest publish wins. Values that already equal the published ones create no version, but are still written into the draft. When the store has nothing published yet, a first version goes live with these values and the draft's tone, which the agent already uses; the agent stays off unless you pass `enabled` true, and the persona gets the store's default name unless you pass `personaName`; the draft's other edits stay pending. NO_UPDATE_FIELDS when you pass no setting. `brandName`, `brandBio` and `excludeSmsProviderUnsubscribers` are saved too; `brandName` and `excludeSmsProviderUnsubscribers` need a user with Set marketing settings, so an API key is refused (403). If the bio or the SMS option cannot be saved, the settings are still published and the call fails with 503 LIVE_FIELDS_NOT_SAVED naming them; repeat the call with only those fields. Returns the `PUBLISHED` version with its `revision`; null when the store still has nothing published, because the call created no first version (the draft is left as it was; `brandBio` and `excludeSmsProviderUnsubscribers` are still saved) or the store has no Commerce Agent account (nothing is saved). BAD_USER_INPUT for a null or a value outside its limits. Refused with 403 when it turns on iMessage, RCS or extended outreach the store cannot use, or changes `returnWindowGrace` with an API key or without Set returns and claims settings, or names `SHOP_PAY` in `capabilityGuidance` for a store that does not have Shop Pay; with 404 NOT_FOUND when an escalation guideline's `knowledgeId` is not one of the store's; with 409 when `discount` is set for a store that still has an enabled support discount not yet moved to the Commerce Agent.

**Required scopes:** [`commerce_agent_settings_publish`](https://developers.redo.com/docs/api-reference/v3/reference/scopes#scope-commerce_agent_settings_publish)

## Arguments

**input** `[CommerceAgentConfigInput!](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-config-input)` *required*

The settings to publish. Pass at least one field.

**fields**

**brandBio** `String`

A short description of the brand, at most 4000 characters. Leave it out to keep the stored value. Not null. Goes live at once, with commerceAgentConfigPublish only; commerceAgentConfigDraftUpdate refuses it (LIVE\_ONLY\_FIELD).

**brandName** `String`

What the agent calls the store, at most 100 characters. Leave it out to keep the stored value. Not null: an empty string goes back to the store name. Goes live at once, with commerceAgentConfigPublish only; commerceAgentConfigDraftUpdate refuses it (LIVE\_ONLY\_FIELD).

**capabilityGuidance** `[\[CommerceAgentConfigCapabilityGuidanceInput!\]](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-config-capability-guidance-input)`

Guidance for the capabilities you name, at least one. A capability you leave out keeps its guidance. `SHOP_PAY` is refused (403) for a store that does not have Shop Pay. Leave it out to keep the stored value. Not null.

**fields**

**capability** `[CommerceAgentCapability!](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-capability)` *required*

The capability the guidance is for. Name each once.

**guidance** `String`

The guidance, at most 2000 characters. Required: pass null to clear it. Surrounding spaces are trimmed, and a blank guidance clears it.

**channels** `[CommerceAgentConfigChannelsInput](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-config-channels-input)`

Outreach channels.

**fields**

**email** `[CommerceAgentConfigChannelInput](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-config-channel-input)`

Email.

**extendedOutreach** `[CommerceAgentConfigChannelInput](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-config-channel-input)`

Extended outreach. Turning the agent on (`enabled` true while the agent is off in the version you change) also switches it on, unless you set this too.

**iMessage** `[CommerceAgentConfigChannelInput](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-config-channel-input)`

iMessage.

**rcs** `[CommerceAgentConfigChannelInput](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-config-channel-input)`

Rich text messages (RCS).

**sms** `[CommerceAgentConfigChannelInput](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-config-channel-input)`

Text messages.

**discount** `[CommerceAgentConfigDiscountInput](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-config-discount-input)`

The discount the agent may offer.

**fields**

**discountCodeId** `ID`

The DiscountCode the agent may offer: an id from `discountCodes`. Leave it out to keep the stored value. Null unlinks it.

**offered** `Boolean`

Whether the agent offers the discount. False keeps the link and stops the offers. Leave it out to keep the stored value. Not null.

**proclivity** `[CommerceAgentDiscountProclivity](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-discount-proclivity)`

How readily the agent offers the discount. Leave it out to keep the stored value. Not null.

**enabled** `Boolean`

Whether the Commerce Agent is on. Turning it on (true while the agent is off in the version you change) also switches extended outreach on, unless `channels.extendedOutreach` is set or the store's plan has none; true for an agent already on changes nothing. Leave it out to keep the stored value. Not null.

**escalation** `[CommerceAgentConfigEscalationInput](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-config-escalation-input)`

Handing conversations to the support team.

**fields**

**contactEmail** `String`

The email address the agent tells shoppers to write to, at most 254 characters. Leave it out to keep the stored value. Not null: an empty string clears it. Left out of the developer log.

**escalateToSupport** `Boolean`

Whether the agent may hand a conversation to support. Leave it out to keep the stored value. Not null.

**escalationGuidelines** `[\[CommerceAgentConfigEscalationGuidelineInput!\]](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-config-escalation-guideline-input)`

The whole list of rules for keeping a conversation instead of handing it to the support team, in order: at most 20. It replaces the stored list; an empty list clears it. Leave it out to keep the stored value. Not null.

**fields**

**knowledgeId** `ID`

The id of the knowledge entry that holds the policy behind the rule, such as a `KnowledgeArticle` id. Leave it out, or pass null, to link none. An id the store does not have is refused (404 NOT\_FOUND), and one that is not a knowledge entry's id, such as a product id, is 400 BAD\_USER\_INPUT.

**rule** `String!` *required*

The rule, at most 500 characters. Not empty.

**excludeSmsProviderUnsubscribers** `Boolean`

Goes live at once, with commerceAgentConfigPublish only; commerceAgentConfigDraftUpdate refuses it (LIVE\_ONLY\_FIELD).

**guidelines** `[String!]`

The whole list of guidelines, in order: at most 20, each at most 500 characters. It replaces the stored list; an empty list clears it. Leave it out to keep the stored value. Not null.

**personaName** `String`

The name the agent goes by, at most 64 characters. Leave it out to keep the stored value. Not null: an empty string clears it.

**recontactCooldownHours** `Int`

Hours before the agent contacts the same shopper again, from 1 to 8760. Leave it out to keep the stored value. Null goes back to the default.

**repliesEnabled** `Boolean`

Whether the agent replies to shoppers who write back. Leave it out to keep the stored value. Not null.

**returnWindowGrace** `[CommerceAgentConfigReturnWindowGraceInput](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-config-return-window-grace-input)`

Late-return cutoffs.

**fields**

**agentDays** `Int`

Days past the window the agent may accept a return on its own. Leave it out to keep the stored value. Not null.

**teamReviewDays** `Int`

Days past the window a return goes to the team for review. At least `agentDays`. Leave it out to keep the stored value. Not null.

**tone** `[CommerceAgentConfigToneInput](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-config-tone-input)`

Tone and voice.

**fields**

**formalityCasualness** `[CommerceAgentToneRangeInput](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-tone-range-input)`

From formal (1) to casual (5).

**matterOfFactEnthusiasm** `[CommerceAgentToneRangeInput](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-tone-range-input)`

From matter-of-fact (1) to enthusiastic (5).

**respectfulnessIrreverence** `[CommerceAgentToneRangeInput](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-tone-range-input)`

From respectful (1) to irreverent (5).

**seriousnessHumor** `[CommerceAgentToneRangeInput](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-tone-range-input)`

From serious (1) to humorous (5).

**voiceInstructions** `String`

Free-text voice instructions, at most 500 characters. Leave it out to keep the stored value. Not null: an empty string clears them.

## Returns

**commerceAgentConfigPublish** `[CommerceAgentConfig](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-config)`

One version of the Commerce Agent's Playbook settings. `brandBio`, `excludeSmsProviderUnsubscribers` and `capabilities` are live: the same in both versions.

**fields**

**brandBio** `String`

A short description of the brand. Live: one value for both versions, outside `revision`. Null when none is set.

**brandName** `String`

What the agent calls the store. Null means it uses the store name.

**capabilities** `[CommerceAgentConfigCapabilities!](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-config-capabilities)` *required*

What the agent can do today. Read only.

**fields**

**discount** `Boolean!` *required*

Whether the agent has a discount to offer now.

**replies** `Boolean!` *required*

Whether the agent replies to shoppers now. False while the agent is off.

**returns** `Boolean!` *required*

Whether the agent can start returns for shoppers. This follows the store's returns setting, so it can be true while the agent is off.

**capabilityGuidance** `[\[CommerceAgentConfigCapabilityGuidance!\]!](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-config-capability-guidance)` *required*

The merchant's guidance for each capability, one entry per capability, `guidance` null when none is set.

**fields**

**capability** `[CommerceAgentCapability!](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-capability)` *required*

The capability the guidance is for.

**guidance** `String`

The guidance. Null when none is set.

**channels** `[CommerceAgentConfigChannels!](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-config-channels)` *required*

Outreach channels.

**fields**

**email** `[CommerceAgentConfigChannel!](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-config-channel)` *required*

Email. Off until the merchant switches it on.

**fields**

**enabled** `Boolean!` *required*

Whether the channel is switched on in this version. Not reduced by `status`: a channel the store cannot use yet still shows what was chosen.

**status** `[CommerceAgentConfigChannelStatus!](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-config-channel-status)` *required*

Whether the channel can send, from this version's switch plus the store's live access. Access is the same in both versions.

**extendedOutreach** `[CommerceAgentConfigChannel!](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-config-channel)` *required*

Extended outreach: Commerce Agent's messages beyond replies, such as cart recovery.

**fields**

**enabled** `Boolean!` *required*

Whether the channel is switched on in this version. Not reduced by `status`: a channel the store cannot use yet still shows what was chosen.

**status** `[CommerceAgentConfigChannelStatus!](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-config-channel-status)` *required*

Whether the channel can send, from this version's switch plus the store's live access. Access is the same in both versions.

**iMessage** `[CommerceAgentConfigChannel!](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-config-channel)` *required*

iMessage.

**fields**

**enabled** `Boolean!` *required*

Whether the channel is switched on in this version. Not reduced by `status`: a channel the store cannot use yet still shows what was chosen.

**status** `[CommerceAgentConfigChannelStatus!](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-config-channel-status)` *required*

Whether the channel can send, from this version's switch plus the store's live access. Access is the same in both versions.

**rcs** `[CommerceAgentConfigChannel!](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-config-channel)` *required*

Rich text messages (RCS).

**fields**

**enabled** `Boolean!` *required*

Whether the channel is switched on in this version. Not reduced by `status`: a channel the store cannot use yet still shows what was chosen.

**status** `[CommerceAgentConfigChannelStatus!](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-config-channel-status)` *required*

Whether the channel can send, from this version's switch plus the store's live access. Access is the same in both versions.

**sms** `[CommerceAgentConfigChannel!](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-config-channel)` *required*

Text messages. On until the merchant switches it off.

**fields**

**enabled** `Boolean!` *required*

Whether the channel is switched on in this version. Not reduced by `status`: a channel the store cannot use yet still shows what was chosen.

**status** `[CommerceAgentConfigChannelStatus!](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-config-channel-status)` *required*

Whether the channel can send, from this version's switch plus the store's live access. Access is the same in both versions.

**discount** `[CommerceAgentConfigDiscount!](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-config-discount)` *required*

The discount the agent may offer.

**fields**

**discountCodeId** `ID`

The DiscountCode the agent may offer. Null when none is linked, or when the discount code was deleted.

**offered** `Boolean!` *required*

Whether the agent offers the discount. False keeps the link and stops the offers.

**proclivity** `[CommerceAgentDiscountProclivity](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-discount-proclivity)`

How readily the agent offers the discount. Null when it was never set.

**enabled** `Boolean!` *required*

Whether the Commerce Agent is on.

**escalation** `[CommerceAgentConfigEscalation!](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-config-escalation)` *required*

Handing conversations to the support team.

**fields**

**contactEmail** `String`

The email address the agent tells shoppers to write to. Null when none is set. Left out of the developer log.

**escalateToSupport** `Boolean!` *required*

Whether the agent may hand a conversation to support.

**escalationGuidelines** `[\[CommerceAgentConfigEscalationGuideline!\]!](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-config-escalation-guideline)` *required*

The rules for keeping a conversation instead of handing it to the support team, in the order the merchant set them.

**fields**

**knowledgeId** `ID`

The id of the knowledge entry that holds the policy behind the rule, such as a `KnowledgeArticle` id. Null when none is linked.

**rule** `String!` *required*

The rule, as the agent reads it.

**excludeSmsProviderUnsubscribers** `Boolean!` *required*

Whether texts skip shoppers who unsubscribed through another SMS provider. Live: one value for both versions, outside `revision`.

**guidelines** `[String!]!` *required*

The merchant's guidelines for the agent, in order.

**personaName** `String`

The name the agent goes by. Null when none is set; an empty string when it was cleared.

**recontactCooldownHours** `Int`

Hours before the agent contacts the same shopper again. Null means the default.

**repliesEnabled** `Boolean!` *required*

Whether the agent replies to shoppers who write back. A version with no stored choice reads true, as the agent does.

**returnWindowGrace** `[CommerceAgentConfigReturnWindowGrace](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-config-return-window-grace)`

Late-return cutoffs. Null when none are set.

**fields**

**agentDays** `Int!` *required*

Days past the window the agent may accept a return on its own.

**teamReviewDays** `Int!` *required*

Days past the window a return goes to the team for review. At least `agentDays`.

**revision** `String!` *required*

Identifies this version's content. It changes when any setting in the version changes, including settings this type does not show: instant exchanges, knowledge auto-apply, email replies, Shop Pay and guideline rules. It identifies what is stored, so saving a setting again with the same effective value, such as switching off a channel that was already off, can change it too. A fresh draft has the published revision. Live fields are not part of it.

**tone** `[CommerceAgentConfigTone!](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-config-tone)` *required*

Tone and voice. A version with no stored choice reads the default sliders.

**fields**

**formalityCasualness** `[CommerceAgentToneRange!](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-tone-range)` *required*

From formal (1) to casual (5).

**fields**

**max** `Int!` *required*

The high end, from 1 to 5.

**min** `Int!` *required*

The low end, from 1 to 5.

**matterOfFactEnthusiasm** `[CommerceAgentToneRange!](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-tone-range)` *required*

From matter-of-fact (1) to enthusiastic (5).

**fields**

**max** `Int!` *required*

The high end, from 1 to 5.

**min** `Int!` *required*

The low end, from 1 to 5.

**respectfulnessIrreverence** `[CommerceAgentToneRange!](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-tone-range)` *required*

From respectful (1) to irreverent (5).

**fields**

**max** `Int!` *required*

The high end, from 1 to 5.

**min** `Int!` *required*

The low end, from 1 to 5.

**seriousnessHumor** `[CommerceAgentToneRange!](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-tone-range)` *required*

From serious (1) to humorous (5).

**fields**

**max** `Int!` *required*

The high end, from 1 to 5.

**min** `Int!` *required*

The low end, from 1 to 5.

**voiceInstructions** `String`

Free-text voice instructions. Null when none are set.

## Example

```graphql theme={null}
mutation {
  commerceAgentConfigPublish(input: { ... }) {
    brandBio
    brandName
    enabled
    excludeSmsProviderUnsubscribers
    guidelines
    personaName
    recontactCooldownHours
    repliesEnabled
    # ...
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.