inbox

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/hellou-ai/json-schema/hellou-ai-inbox-schema.json",
  "title": "inbox",
  "x-generated": "2026-11-11",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/hellou-ai-openapi.json#/components/schemas/inbox",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "ID of the inbox"
    },
    "name": {
      "type": "string",
      "description": "The name of the inbox"
    },
    "website_url": {
      "type": "string",
      "description": "Website URL"
    },
    "channel_type": {
      "type": "string",
      "description": "The type of the inbox"
    },
    "avatar_url": {
      "type": "string",
      "description": "The avatar image of the inbox"
    },
    "widget_color": {
      "type": "string",
      "description": "Widget Color used for customization of the widget"
    },
    "website_token": {
      "type": "string",
      "description": "Website Token"
    },
    "enable_auto_assignment": {
      "type": "boolean",
      "description": "The flag which shows whether Auto Assignment is enabled or not"
    },
    "web_widget_script": {
      "type": "string",
      "description": "Script used to load the website widget"
    },
    "welcome_title": {
      "type": [
        "string",
        "null"
      ],
      "description": "Welcome title to be displayed on the widget"
    },
    "welcome_tagline": {
      "type": [
        "string",
        "null"
      ],
      "description": "Welcome tagline to be displayed on the widget"
    },
    "allowed_domains": {
      "type": [
        "string",
        "null"
      ],
      "description": "Sites allowed to embed the website widget, one per line (example.com, *.example.com, https://app.example.com:8443). Empty or null lets any site embed it."
    },
    "greeting_enabled": {
      "type": "boolean",
      "description": "The flag which shows whether greeting is enabled"
    },
    "greeting_message": {
      "type": [
        "string",
        "null"
      ],
      "description": "A greeting message when the user starts the conversation"
    },
    "appearance": {
      "type": "object",
      "description": "Website inboxes only. The widget's resolved look: defaults, legacy\nsettings and the saved overrides merged. Only the bubble theme, the\nlauncher and the cards over the launcher are described here.\n",
      "properties": {
        "bubble_theme": {
          "$ref": "#/$defs/inbox_bubble_theme"
        },
        "launcher": {
          "$ref": "#/$defs/inbox_launcher_appearance"
        },
        "cards": {
          "$ref": "#/$defs/inbox_cards_appearance"
        }
      }
    },
    "appearance_overrides": {
      "type": "object",
      "description": "Website inboxes only. Just the values saved for this inbox, without the\ndefaults. Same shape as `appearance`.\n",
      "properties": {
        "bubble_theme": {
          "$ref": "#/$defs/inbox_bubble_theme"
        },
        "launcher": {
          "$ref": "#/$defs/inbox_launcher_appearance"
        },
        "cards": {
          "$ref": "#/$defs/inbox_cards_appearance"
        }
      }
    },
    "reauthorization_required": {
      "type": "boolean",
      "description": "Present on Facebook, WhatsApp and Microsoft or Google email inboxes.\n`true` when the provider rejected the inbox's credentials and the inbox\nmust be reconnected from its settings.\n"
    },
    "webhook_unhealthy": {
      "type": "boolean",
      "description": "WhatsApp inboxes only. `true` when the daily check found that Meta is\nnot delivering this number's messages to this installation (the\ncallback URL differs or the app is not subscribed). Reconnecting the\ninbox registers the webhook again and clears the flag.\n"
    },
    "whatsapp_coexistence": {
      "type": "object",
      "description": "WhatsApp inboxes on the WhatsApp Business app (coexistence), for\nadministrators only. Absent for any other inbox.\n",
      "properties": {
        "is_on_biz_app": {
          "type": "boolean",
          "description": "Always `true` when this object is present."
        },
        "contacts_sync": {
          "type": [
            "object",
            "null"
          ],
          "description": "The one-time import of the Business app contacts.",
          "properties": {
            "status": {
              "type": "string",
              "enum": [
                "requested",
                "complete",
                "failed"
              ],
              "description": "`requested` once Meta accepted the request, `complete` once the\nfirst contacts arrived, `failed` when Meta refused it.\n"
            },
            "requested_at": {
              "type": "string",
              "format": "date-time",
              "description": "When the request was accepted."
            },
            "completed_at": {
              "type": "string",
              "format": "date-time",
              "description": "When the first contacts arrived."
            },
            "contacts_added": {
              "type": "integer",
              "description": "New contacts created from the Business app contacts so far."
            },
            "error": {
              "type": [
                "string",
                "null"
              ],
              "description": "Meta's reason when the sync failed."
            }
          }
        },
        "history_sync": {
          "type": [
            "object",
            "null"
          ],
          "description": "The one-time import of the Business app chat history.",
          "properties": {
            "status": {
              "type": "string",
              "enum": [
                "requested",
                "in_progress",
                "complete",
                "declined",
                "failed"
              ],
              "description": "`declined` when the business turned history sharing off in the\nBusiness app.\n"
            },
            "progress": {
              "type": "integer",
              "description": "Percent of the history received, 0 to 100."
            },
            "requested_at": {
              "type": "string",
              "format": "date-time",
              "description": "When the request was accepted."
            },
            "error": {
              "type": [
                "string",
                "null"
              ],
              "description": "Meta's reason when the sync failed."
            }
          }
        },
        "offboarded": {
          "type": [
            "object",
            "null"
          ],
          "description": "Set when Meta reported that the number was disconnected from this app.",
          "properties": {
            "event": {
              "type": "string",
              "description": "Meta's account event, `PARTNER_REMOVED` or `ACCOUNT_OFFBOARDED`."
            },
            "reason": {
              "type": "string",
              "description": "Meta's disconnection reason."
            },
            "initiated_by": {
              "type": "string",
              "description": "Who disconnected the number."
            },
            "at": {
              "type": "string",
              "format": "date-time",
              "description": "When this installation was told."
            }
          }
        }
      }
    },
    "csat_config": {
      "type": "object",
      "description": "How the CSAT survey is shown. An empty object when the inbox keeps the default emoji survey",
      "properties": {
        "display_type": {
          "type": "string",
          "enum": [
            "emoji",
            "star"
          ],
          "description": "Rating widget of the survey. Both store the same 1 to 5 rating"
        },
        "message": {
          "type": "string",
          "maxLength": 500,
          "description": "Optional text shown above the rating. Plain text"
        }
      }
    }
  },
  "$defs": {
    "inbox_bubble_theme": {
      "type": "string",
      "enum": [
        "app",
        "bocadillo",
        "soft_brutal",
        "echo"
      ],
      "default": "app",
      "description": "One look for the launcher, the chat panel (messages, quick-reply chips,\navatars, composer, send button) and the minimized text card. `app` is the\ncurrent look. `bocadillo` gives each shape one square corner, like the Hellou\nmark. `soft_brutal` draws ink outlines with hard offset shadows. `echo` adds a\nfaint offset copy behind each shape. Motion uses transform and opacity only\nand stops for visitors whose device asks to reduce motion. This is separate\nfrom `theme`, which is the light, dark or auto colour scheme.\n"
    },
    "inbox_cards_appearance": {
      "type": "object",
      "description": "The cards shown over the closed launcher of the website widget. Every card\nis off until it is turned on for the inbox.\n",
      "properties": {
        "greeting": {
          "type": "object",
          "description": "A hello shown 8 seconds after the page loads, to a visitor with no\nconversation. The cross dismisses it for the visit; a tap opens the chat.\nOutside business hours the away card takes its place when it is on.\n",
          "properties": {
            "enabled": {
              "type": "boolean",
              "default": false,
              "description": "Whether the greeting shows."
            },
            "text": {
              "type": "object",
              "additionalProperties": {
                "type": "string",
                "maxLength": 120
              },
              "description": "Greeting per language code, at most 120 characters each. A language\nwith no text gets the widget's own hello. An update replaces the whole\nmap.\n"
            }
          }
        },
        "away": {
          "type": "object",
          "description": "Outside business hours, a card that says when the team is back and where\nthe reply will arrive (in the chat, and by email when the visitor gave\none). It needs working hours turned on for the inbox.\n",
          "properties": {
            "enabled": {
              "type": "boolean",
              "default": false,
              "description": "Whether the away card shows."
            }
          }
        },
        "typing": {
          "type": "object",
          "description": "Who is typing, shown while the chat is closed.",
          "properties": {
            "enabled": {
              "type": "boolean",
              "default": false,
              "description": "Whether the typing card shows."
            }
          }
        },
        "quick_replies": {
          "type": "object",
          "description": "An AI agent's question with up to three answers, shown while the chat is\nclosed. An answer opens the chat and sends it. It needs an agent that\nsends questions with answers (message content type `input_select`).\n",
          "properties": {
            "enabled": {
              "type": "boolean",
              "default": false,
              "description": "Whether the question card shows."
            }
          }
        }
      }
    },
    "inbox_launcher_appearance": {
      "type": "object",
      "description": "The round button that opens the website widget.",
      "properties": {
        "icon": {
          "type": "string",
          "enum": [
            "hellou",
            "question",
            "headset",
            "phone",
            "sparkle",
            "message",
            "typing",
            "hellou_animated",
            "duo",
            "sparkle_animated",
            "headset_animated",
            "wave",
            "heart",
            "cursor",
            "phone_animated",
            "face",
            "custom"
          ],
          "description": "Glyph drawn on the launcher. `hellou` (the default), `question`,\n`headset`, `phone`, `sparkle` and `message` are still glyphs. `typing`,\n`hellou_animated`, `duo`, `sparkle_animated`, `headset_animated`, `wave`,\n`heart`, `cursor`, `phone_animated` and `face` are animated; the\nanimation stays still for visitors whose device asks to reduce motion.\nEvery icon turns into the same close mark while the chat is open.\n`custom` draws the uploaded launcher image. The retired value `chat` is\nstill accepted and reads as `hellou`.\n"
        },
        "image_url": {
          "type": [
            "string",
            "null"
          ],
          "format": "uri",
          "description": "Public URL of the uploaded launcher image, or null when there is none.\nThe `v` query parameter changes with the picture, so the URL can be cached.\n"
        },
        "style": {
          "type": "string",
          "enum": [
            "bubble",
            "card"
          ],
          "description": "`bubble` is the round button. `card` is the minimized text card: a prompt\nline and a button label (see `card`). On screens below the mobile\nbreakpoint the card collapses to the bubble unless `card.on_mobile` is\ntrue. \"Powered by HellouOne\" under the card follows the inbox's\n`show_branding` and the plan, as it does in the open widget.\n"
        },
        "shape": {
          "type": "string",
          "enum": [
            "bubble",
            "pill"
          ],
          "default": "bubble",
          "description": "`bubble` is the 64px round button. `pill` is the 48px button that carries\nthe label next to the icon (the label falls back to the widget's own\n\"Chat with us\" text) and stays a pill on phones. The shape is independent\nof `style`: a minimized text card keeps the launcher shape for its\nfallback bubble.\n"
        },
        "card": {
          "type": "object",
          "description": "Texts and behaviour of the minimized text card (`style` = `card`).",
          "properties": {
            "text": {
              "type": "object",
              "additionalProperties": {
                "type": "string",
                "maxLength": 60
              },
              "description": "Prompt line per language code, at most 60 characters each. An update\nreplaces the whole map.\n"
            },
            "cta": {
              "type": "object",
              "additionalProperties": {
                "type": "string",
                "maxLength": 24
              },
              "description": "Button label per language code, at most 24 characters each. An update\nreplaces the whole map.\n"
            },
            "link": {
              "type": "object",
              "description": "Optional second link under the card, for example \"or book a demo\". It\nshows only when it has a label for the visitor's language and an url.\n",
              "properties": {
                "label": {
                  "type": "object",
                  "additionalProperties": {
                    "type": "string",
                    "maxLength": 30
                  },
                  "description": "Link text per language code, at most 30 characters each. An update\nreplaces the whole map.\n"
                },
                "url": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "format": "uri",
                  "maxLength": 500,
                  "description": "Where the link opens, in a new tab. `https://` with a host only\n(no `http:`, `javascript:`, `data:`, protocol-relative or\ncredentials in the address), at most 500 characters. null\nremoves it.\n"
                }
              }
            },
            "on_mobile": {
              "type": "boolean",
              "default": false,
              "description": "When false, below the mobile breakpoint the card collapses to the\nbubble.\n"
            }
          }
        }
      }
    }
  }
}