--- title: "Update the AI configuration" method: PATCH path: "/ai/config" tags: ["AI configuration"] --- # Update the AI configuration `PATCH /ai/config` ## Request - Base URL: `https://sumgenius.ai/api/v1` - URL: `https://sumgenius.ai/api/v1/ai/config` - Auth: one of: - API key in header `X-SumGenius-Api-Key` - HTTP bearer Send any subset of sections, each with any subset of its fields. Omitted fields keep their values. off_limits merges per category. Changing starters publishes to Instagram and Facebook at once, like the portal. Never touches the per-channel AI on/off switches. Requires the `admin` scope. ## Request body - AiConfigUpdate: Any subset of sections, each with any subset of its fields. - `identity` object - `name` string, nullable: What the AI calls itself. - `tone` 'casual' | 'professional' | 'formal' - `instructions` string: The custom rules and guidelines. The system prompt the business writes. - `welcome_message` string, nullable: Sent as written on the first message of every new conversation. Null for no greeting. - `welcome_mode` 'combined' | 'standalone': combined: welcome and the AI answer in one message. standalone: welcome only, the AI answers the next message. - `website_url` string, nullable - `business_contact_email` string, nullable - `business_contact_phone` string, nullable - `default_customer_language` 'en' | 'es' | 'zh' | 'fr' | 'de' | 'pt' | 'ja' | 'ru' | 'hi' | 'ar' | 'it' | 'ko' | 'nl' | 'cs' | 'pl' | 'tr' | 'sv' | 'da' | 'no' | 'ro' | 'hu' | 'uk' | 'el' | 'vi' | 'id' | 'th' | 'tl' | 'he' | 'null', nullable: Customer language, used until a lead's own language is known: for the AI reply to a message with no real words (an emoji, "ok", a name) and for automated messages (flow prompts, booking times, CSAT survey, fallback replies). Null means Automatic: the AI follows the language of the instructions and automated messages use English. - `behavior` object - `goals` string[] - `batch_messages` boolean: Wait for rapid follow-up messages before answering. - `batch_window_ms` integer - `auto_escalation` boolean: Hand to a human on frustration or an explicit request. - `copilot_enabled` boolean: The AI drafts, a person approves. - `reply_pacing` 'instant' | 'quick' | 'natural' | 'relaxed': How long after the lead's last message an AI reply arrives. instant: as soon as it is written. quick: about 15 to 30 seconds. natural: about 30 to 60. relaxed: about 60 to 90. Anything but instant turns batching on. - `restrictions` object - `off_limits` object: Send only the categories to change. - `legal` boolean - `medical` boolean - `competitors` boolean - `pricing` boolean - `personal` boolean - `offtopic` boolean - `solicitation_pause` boolean - `starters` object - `instagram` object - `enabled` boolean - `questions` string[] - `facebook` object - `enabled` boolean - `mode` 'ice_breakers' | 'get_started': ice_breakers shows questions, get_started shows one button. - `questions` string[] - `file_handling` object - `enabled` boolean: One switch for images, documents and videos. Enabling forces batching on. - `auto_escalate_on_image` boolean - `auto_escalate_on_document` boolean - `auto_escalate_on_video` boolean - `escalate_if_team_online` boolean - `followups` object - `enabled` boolean - `first_delay_minutes` integer - `second_delay_hours` integer - `quiet_hours` object - `enabled` boolean - `start` string - `end` string - `csat` object - `enabled` boolean - `template` 'simple' | 'friendly' | 'professional' | 'custom' - `custom_message` string - `comment_ai` object - `enabled` boolean: Run the AI Comment Manager on comments no trigger claimed. - `mode` 'auto' | 'approval': auto posts replies at once; approval queues them under /comments. - `instructions` string: Extra guidance for comment replies, on top of the knowledge base and the AI identity. - `reply_length` 'short' | 'medium' | 'detailed': short is 1 to 2 sentences, medium 2 to 3, detailed 3 to 5. - `moderation` object: Categories that get the comment hidden. True means hide. Send only the categories to change. - `spam` boolean - `profanity` boolean - `negativity` boolean - `competitor_links` boolean - `self_promotion` boolean - `dm_on_hide` boolean: DM the person when their comment is hidden. - `dm_message` string: That DM. {name} is the commenter. - `exclude_rules` object[]: Skip comments on these posts, or containing these words. Replaces the whole list. - `type` 'post_id' | 'keyword', required - `value` string, required - `booking` object - `enabled` boolean: AI Booking. Off means the AI declines booking requests; the portal and the API can still book. - `google_meet_invites` boolean: Send a Google Meet link and email invite for services marked virtual. Needs Google Calendar connected (409 not_connected otherwise) and forces email to required. - `required_fields` object: What the customer must provide to book. Send only the keys to change. - `name` boolean - `email` boolean - `phone` boolean - `address` boolean - `vehicle` boolean - `cost` boolean - `address_parts` object: Only meaningful when address is required. - `city` boolean - `state` boolean - `street` boolean ## Response `200` OK - object - `data` AiConfig, required - `identity` object - `name` string, nullable: What the AI calls itself. - `tone` 'casual' | 'professional' | 'formal' - `instructions` string: The custom rules and guidelines. The system prompt the business writes. - `welcome_message` string, nullable: Sent as written on the first message of every new conversation. Null for no greeting. - `welcome_mode` 'combined' | 'standalone': combined: welcome and the AI answer in one message. standalone: welcome only, the AI answers the next message. - `website_url` string, nullable - `business_contact_email` string, nullable - `business_contact_phone` string, nullable - `default_customer_language` 'en' | 'es' | 'zh' | 'fr' | 'de' | 'pt' | 'ja' | 'ru' | 'hi' | 'ar' | 'it' | 'ko' | 'nl' | 'cs' | 'pl' | 'tr' | 'sv' | 'da' | 'no' | 'ro' | 'hu' | 'uk' | 'el' | 'vi' | 'id' | 'th' | 'tl' | 'he' | 'null', nullable: Customer language, used until a lead's own language is known: for the AI reply to a message with no real words (an emoji, "ok", a name) and for automated messages (flow prompts, booking times, CSAT survey, fallback replies). Null means Automatic: the AI follows the language of the instructions and automated messages use English. - `instructions_source` 'auto' | 'manual' | 'null', nullable - `behavior` object - `goals` string[] - `batch_messages` boolean: Wait for rapid follow-up messages before answering. - `batch_window_ms` integer - `auto_escalation` boolean: Hand to a human on frustration or an explicit request. - `copilot_enabled` boolean: The AI drafts, a person approves. - `reply_pacing` 'instant' | 'quick' | 'natural' | 'relaxed': How long after the lead's last message an AI reply arrives. instant: as soon as it is written. quick: about 15 to 30 seconds. natural: about 30 to 60. relaxed: about 60 to 90. Anything but instant turns batching on. - `business_hours` object[] - `day` 'sunday' | 'monday' | 'tuesday' | 'wednesday' | 'thursday' | 'friday' | 'saturday' - `closed` boolean - `open` string, nullable: HH:MM - `close` string, nullable: HH:MM - `restrictions` object - `off_limits` object: Topics the AI refuses. True means off limits. - `legal` boolean - `medical` boolean - `competitors` boolean - `pricing` boolean - `personal` boolean - `offtopic` boolean - `solicitation_pause` boolean: Pause the AI on conversations that look like solicitation. - `starters` object - `instagram` object - `enabled` boolean - `questions` string[] - `facebook` object - `enabled` boolean - `mode` 'ice_breakers' | 'get_started': ice_breakers shows questions, get_started shows one button. - `questions` string[] - `published` object: Read-only publish state per platform. - `instagram_at` string, date-time, nullable: UTC ISO-8601. - `instagram_error` string, nullable - `facebook_at` string, date-time, nullable: UTC ISO-8601. - `facebook_error` string, nullable - `file_handling` object - `available` boolean: Whether the plan includes this. - `enabled` boolean: One switch for images, documents and videos. Enabling forces batching on. - `auto_escalate_on_image` boolean - `auto_escalate_on_document` boolean - `auto_escalate_on_video` boolean - `escalate_if_team_online` boolean - `followups` object - `available` boolean - `enabled` boolean - `first_delay_minutes` integer - `second_delay_hours` integer - `quiet_hours` object - `enabled` boolean - `start` string - `end` string - `csat` object - `available` boolean - `enabled` boolean - `template` 'simple' | 'friendly' | 'professional' | 'custom' - `custom_message` string - `comment_ai` object - `available` boolean: Pro plans and above. - `enabled` boolean: Run the AI Comment Manager on comments no trigger claimed. - `mode` 'auto' | 'approval': auto posts replies at once; approval queues them under /comments. - `instructions` string: Extra guidance for comment replies, on top of the knowledge base and the AI identity. - `reply_length` 'short' | 'medium' | 'detailed': short is 1 to 2 sentences, medium 2 to 3, detailed 3 to 5. - `moderation` object: Categories that get the comment hidden. True means hide. Send only the categories to change. - `spam` boolean - `profanity` boolean - `negativity` boolean - `competitor_links` boolean - `self_promotion` boolean - `dm_on_hide` boolean: DM the person when their comment is hidden. - `dm_message` string: That DM. {name} is the commenter. - `exclude_rules` object[]: Skip comments on these posts, or containing these words. Replaces the whole list. - `type` 'post_id' | 'keyword', required - `value` string, required - `booking` object - `enabled` boolean: AI Booking. Off means the AI declines booking requests; the portal and the API can still book. - `google_meet_invites` boolean: Send a Google Meet link and email invite for services marked virtual. Needs Google Calendar connected (409 not_connected otherwise) and forces email to required. - `required_fields` object: What the customer must provide to book. Send only the keys to change. - `name` boolean - `email` boolean - `phone` boolean - `address` boolean - `vehicle` boolean - `cost` boolean - `address_parts` object: Only meaningful when address is required. - `city` boolean - `state` boolean - `street` boolean - `timing` object: Read-only. No portal control yet; defaults for every account. - `buffer_minutes` integer - `min_advance_hours` integer - `max_advance_days` integer - `reminder_hours` integer - `timezone` string, nullable - `calendar` object: Read-only. - `google_calendar_connected` boolean - `ghl_connected` boolean - `bookable_services` object[]: Service menu rows with a duration. Manage them under /knowledge/services. - `id` integer - `name` string - `duration_minutes` integer - `price` string, nullable - `is_virtual` boolean ## Other responses - `400`: Error envelope. Codes: `invalid_param`: 400 a parameter or body field failed validation; `param` names it `invalid_json`: 400 the body is not valid JSON `invalid_idempotency_key`: 400 Idempotency-Key is not 1 to 128 printable ASCII characters `unauthorized`: 401 no API key sent `invalid_api_key`: 401 the key is not recognised `addon_inactive`: 403 the key is valid but the Webhook & API add-on is not active `insufficient_scope`: 403 the key scope does not cover this endpoint; carries `required_scope` and `key_scope` `feature_unavailable`: 403 the plan does not include this feature; `param` names it `already_blocked`: 409 that person is already on the AI blocklist `plan_limit_reached`: 403 the plan cap for this resource is reached (for example knowledge base items) `already_member`: 409 that email is already a team member `limit_reached`: 409 the product cap for this resource is reached (3 webhook endpoints, 10 active keys); remove one first `cannot_revoke_self`: 409 a key cannot revoke itself `too_soon`: 429 the same invitation was resent moments ago; the message says how long to wait `governance_incomplete`: 422 the endpoint cannot go live until its data-sharing declaration is attested with a purpose `invitation_pending`: 409 that email already has a pending invitation; resend or cancel it `not_found`: 404 missing, or not owned by your account `method_not_allowed`: 405 wrong method; the Allow header lists valid ones `idempotency_in_progress`: 409 a request with this Idempotency-Key is still running `resume_blocked`: 409 the AI pause on this conversation was set by a solicitation pause, a fraud flag or a connected-account pause; lift it from the portal `blocked`: 409 the customer is on the AI blocklist `opted_out`: 409 the customer opted out of automated messages `window_closed`: 409 the Meta messaging window for this conversation has closed `purge_active`: 409 SMS AI cannot be switched on while inbound body purge is on `sms_not_ready`: 409 SMS AI cannot be switched on until carrier registration assigns a Messaging Service `idempotency_key_reused`: 422 same Idempotency-Key, different request `unprocessable_send`: 422 a send was permanently rejected by the channel `rate_limited`: 429 quota or burst ceiling reached; Retry-After is set `service_unavailable`: 503 temporary failure; retry as directed `server_error`: 500 unexpected failure on our side `flow_conflict`: The trigger cannot be activated because of its linked flows: more than one, a paused one, or a broken link. The message says which. `not_connected`: The channel you asked about is not connected to this account. `not_pending`: The comment reply is not waiting for approval (already sent, rejected, or never queued). `send_failed`: 422 Meta refused the reply. The row is marked failed; the message has the reason. `slot_unavailable`: The requested time is outside business hours or already booked. The message says which. `missing_fields`: The account requires customer details this booking did not include; missing_fields lists them. `already_cancelled`: The appointment is already cancelled. `not_active`: Only a pending or confirmed appointment can be rescheduled. `not_editable`: The post is in a status that does not allow this: only draft, scheduled and failed posts can be edited or scheduled; published posts cannot be deleted; only scheduled posts can be unscheduled; only failed posts can be retried. `publish_failed`: 422 a platform rejected the post. The row is now failed; post.error_message and results say why. Retry with POST /posts/{id}/retry. `invalid_definition`: 422 the flow definition failed validation; errors lists every problem, warnings the non-blocking ones. `flow_blocked`: 409 the flow manager refused the action (for example no published version yet, a linked comment trigger in use, or a draft edited elsewhere); the message says why. `conflict`: 409 the draft was edited elsewhere since it was read. - `401`: Error envelope. Codes: `invalid_param`: 400 a parameter or body field failed validation; `param` names it `invalid_json`: 400 the body is not valid JSON `invalid_idempotency_key`: 400 Idempotency-Key is not 1 to 128 printable ASCII characters `unauthorized`: 401 no API key sent `invalid_api_key`: 401 the key is not recognised `addon_inactive`: 403 the key is valid but the Webhook & API add-on is not active `insufficient_scope`: 403 the key scope does not cover this endpoint; carries `required_scope` and `key_scope` `feature_unavailable`: 403 the plan does not include this feature; `param` names it `already_blocked`: 409 that person is already on the AI blocklist `plan_limit_reached`: 403 the plan cap for this resource is reached (for example knowledge base items) `already_member`: 409 that email is already a team member `limit_reached`: 409 the product cap for this resource is reached (3 webhook endpoints, 10 active keys); remove one first `cannot_revoke_self`: 409 a key cannot revoke itself `too_soon`: 429 the same invitation was resent moments ago; the message says how long to wait `governance_incomplete`: 422 the endpoint cannot go live until its data-sharing declaration is attested with a purpose `invitation_pending`: 409 that email already has a pending invitation; resend or cancel it `not_found`: 404 missing, or not owned by your account `method_not_allowed`: 405 wrong method; the Allow header lists valid ones `idempotency_in_progress`: 409 a request with this Idempotency-Key is still running `resume_blocked`: 409 the AI pause on this conversation was set by a solicitation pause, a fraud flag or a connected-account pause; lift it from the portal `blocked`: 409 the customer is on the AI blocklist `opted_out`: 409 the customer opted out of automated messages `window_closed`: 409 the Meta messaging window for this conversation has closed `purge_active`: 409 SMS AI cannot be switched on while inbound body purge is on `sms_not_ready`: 409 SMS AI cannot be switched on until carrier registration assigns a Messaging Service `idempotency_key_reused`: 422 same Idempotency-Key, different request `unprocessable_send`: 422 a send was permanently rejected by the channel `rate_limited`: 429 quota or burst ceiling reached; Retry-After is set `service_unavailable`: 503 temporary failure; retry as directed `server_error`: 500 unexpected failure on our side `flow_conflict`: The trigger cannot be activated because of its linked flows: more than one, a paused one, or a broken link. The message says which. `not_connected`: The channel you asked about is not connected to this account. `not_pending`: The comment reply is not waiting for approval (already sent, rejected, or never queued). `send_failed`: 422 Meta refused the reply. The row is marked failed; the message has the reason. `slot_unavailable`: The requested time is outside business hours or already booked. The message says which. `missing_fields`: The account requires customer details this booking did not include; missing_fields lists them. `already_cancelled`: The appointment is already cancelled. `not_active`: Only a pending or confirmed appointment can be rescheduled. `not_editable`: The post is in a status that does not allow this: only draft, scheduled and failed posts can be edited or scheduled; published posts cannot be deleted; only scheduled posts can be unscheduled; only failed posts can be retried. `publish_failed`: 422 a platform rejected the post. The row is now failed; post.error_message and results say why. Retry with POST /posts/{id}/retry. `invalid_definition`: 422 the flow definition failed validation; errors lists every problem, warnings the non-blocking ones. `flow_blocked`: 409 the flow manager refused the action (for example no published version yet, a linked comment trigger in use, or a draft edited elsewhere); the message says why. `conflict`: 409 the draft was edited elsewhere since it was read. - `403`: insufficient_scope (needs admin) or feature_unavailable (plan does not include the section). - `404`: Error envelope. Codes: `invalid_param`: 400 a parameter or body field failed validation; `param` names it `invalid_json`: 400 the body is not valid JSON `invalid_idempotency_key`: 400 Idempotency-Key is not 1 to 128 printable ASCII characters `unauthorized`: 401 no API key sent `invalid_api_key`: 401 the key is not recognised `addon_inactive`: 403 the key is valid but the Webhook & API add-on is not active `insufficient_scope`: 403 the key scope does not cover this endpoint; carries `required_scope` and `key_scope` `feature_unavailable`: 403 the plan does not include this feature; `param` names it `already_blocked`: 409 that person is already on the AI blocklist `plan_limit_reached`: 403 the plan cap for this resource is reached (for example knowledge base items) `already_member`: 409 that email is already a team member `limit_reached`: 409 the product cap for this resource is reached (3 webhook endpoints, 10 active keys); remove one first `cannot_revoke_self`: 409 a key cannot revoke itself `too_soon`: 429 the same invitation was resent moments ago; the message says how long to wait `governance_incomplete`: 422 the endpoint cannot go live until its data-sharing declaration is attested with a purpose `invitation_pending`: 409 that email already has a pending invitation; resend or cancel it `not_found`: 404 missing, or not owned by your account `method_not_allowed`: 405 wrong method; the Allow header lists valid ones `idempotency_in_progress`: 409 a request with this Idempotency-Key is still running `resume_blocked`: 409 the AI pause on this conversation was set by a solicitation pause, a fraud flag or a connected-account pause; lift it from the portal `blocked`: 409 the customer is on the AI blocklist `opted_out`: 409 the customer opted out of automated messages `window_closed`: 409 the Meta messaging window for this conversation has closed `purge_active`: 409 SMS AI cannot be switched on while inbound body purge is on `sms_not_ready`: 409 SMS AI cannot be switched on until carrier registration assigns a Messaging Service `idempotency_key_reused`: 422 same Idempotency-Key, different request `unprocessable_send`: 422 a send was permanently rejected by the channel `rate_limited`: 429 quota or burst ceiling reached; Retry-After is set `service_unavailable`: 503 temporary failure; retry as directed `server_error`: 500 unexpected failure on our side `flow_conflict`: The trigger cannot be activated because of its linked flows: more than one, a paused one, or a broken link. The message says which. `not_connected`: The channel you asked about is not connected to this account. `not_pending`: The comment reply is not waiting for approval (already sent, rejected, or never queued). `send_failed`: 422 Meta refused the reply. The row is marked failed; the message has the reason. `slot_unavailable`: The requested time is outside business hours or already booked. The message says which. `missing_fields`: The account requires customer details this booking did not include; missing_fields lists them. `already_cancelled`: The appointment is already cancelled. `not_active`: Only a pending or confirmed appointment can be rescheduled. `not_editable`: The post is in a status that does not allow this: only draft, scheduled and failed posts can be edited or scheduled; published posts cannot be deleted; only scheduled posts can be unscheduled; only failed posts can be retried. `publish_failed`: 422 a platform rejected the post. The row is now failed; post.error_message and results say why. Retry with POST /posts/{id}/retry. `invalid_definition`: 422 the flow definition failed validation; errors lists every problem, warnings the non-blocking ones. `flow_blocked`: 409 the flow manager refused the action (for example no published version yet, a linked comment trigger in use, or a draft edited elsewhere); the message says why. `conflict`: 409 the draft was edited elsewhere since it was read. - `429`: Error envelope. Codes: `invalid_param`: 400 a parameter or body field failed validation; `param` names it `invalid_json`: 400 the body is not valid JSON `invalid_idempotency_key`: 400 Idempotency-Key is not 1 to 128 printable ASCII characters `unauthorized`: 401 no API key sent `invalid_api_key`: 401 the key is not recognised `addon_inactive`: 403 the key is valid but the Webhook & API add-on is not active `insufficient_scope`: 403 the key scope does not cover this endpoint; carries `required_scope` and `key_scope` `feature_unavailable`: 403 the plan does not include this feature; `param` names it `already_blocked`: 409 that person is already on the AI blocklist `plan_limit_reached`: 403 the plan cap for this resource is reached (for example knowledge base items) `already_member`: 409 that email is already a team member `limit_reached`: 409 the product cap for this resource is reached (3 webhook endpoints, 10 active keys); remove one first `cannot_revoke_self`: 409 a key cannot revoke itself `too_soon`: 429 the same invitation was resent moments ago; the message says how long to wait `governance_incomplete`: 422 the endpoint cannot go live until its data-sharing declaration is attested with a purpose `invitation_pending`: 409 that email already has a pending invitation; resend or cancel it `not_found`: 404 missing, or not owned by your account `method_not_allowed`: 405 wrong method; the Allow header lists valid ones `idempotency_in_progress`: 409 a request with this Idempotency-Key is still running `resume_blocked`: 409 the AI pause on this conversation was set by a solicitation pause, a fraud flag or a connected-account pause; lift it from the portal `blocked`: 409 the customer is on the AI blocklist `opted_out`: 409 the customer opted out of automated messages `window_closed`: 409 the Meta messaging window for this conversation has closed `purge_active`: 409 SMS AI cannot be switched on while inbound body purge is on `sms_not_ready`: 409 SMS AI cannot be switched on until carrier registration assigns a Messaging Service `idempotency_key_reused`: 422 same Idempotency-Key, different request `unprocessable_send`: 422 a send was permanently rejected by the channel `rate_limited`: 429 quota or burst ceiling reached; Retry-After is set `service_unavailable`: 503 temporary failure; retry as directed `server_error`: 500 unexpected failure on our side `flow_conflict`: The trigger cannot be activated because of its linked flows: more than one, a paused one, or a broken link. The message says which. `not_connected`: The channel you asked about is not connected to this account. `not_pending`: The comment reply is not waiting for approval (already sent, rejected, or never queued). `send_failed`: 422 Meta refused the reply. The row is marked failed; the message has the reason. `slot_unavailable`: The requested time is outside business hours or already booked. The message says which. `missing_fields`: The account requires customer details this booking did not include; missing_fields lists them. `already_cancelled`: The appointment is already cancelled. `not_active`: Only a pending or confirmed appointment can be rescheduled. `not_editable`: The post is in a status that does not allow this: only draft, scheduled and failed posts can be edited or scheduled; published posts cannot be deleted; only scheduled posts can be unscheduled; only failed posts can be retried. `publish_failed`: 422 a platform rejected the post. The row is now failed; post.error_message and results say why. Retry with POST /posts/{id}/retry. `invalid_definition`: 422 the flow definition failed validation; errors lists every problem, warnings the non-blocking ones. `flow_blocked`: 409 the flow manager refused the action (for example no published version yet, a linked comment trigger in use, or a draft edited elsewhere); the message says why. `conflict`: 409 the draft was edited elsewhere since it was read. --- [API](https://skmtc.dev/sumgenius/apis/chatgenius-rest-api.md) · [All operations](https://skmtc.dev/sumgenius/apis/chatgenius-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/sumgenius/apis/chatgenius-rest-api/revisions/f1621a748e6f?raw)