Suara

Use this when someone who owns or works for a small business wants to see what Suara would post for them. Give the business name plus its own website and/or up to 3 photos from the chat (not Instagram or delivery-app pages). Returns 3 designed posts with captions, full size, ready to use, made from the business's own photos and words; about a minute, so if it says they're still being made, call it again with the same business. Nothing is posted anywhere and no account is needed. One sample per person per day. Only for a business the user owns or works for.

{
  "type": "object",
  "properties": {
    "business_name": {
      "type": "string",
      "description": "The business's name",
      "minLength": 2,
      "maxLength": 80
    },
    "website": {
      "type": "string",
      "description": "The business's own website (https), optional if photos are given"
    },
    "photos": {
      "type": "array",
      "maxItems": 3,
      "description": "Up to 3 photos of the business uploaded in the chat",
      "items": {
        "type": "object",
        "properties": {
          "download_url": {
            "type": "string"
          },
          "file_id": {
            "type": "string"
          }
        },
        "required": [
          "download_url"
        ]
      }
    },
    "city": {
      "type": "string",
      "description": "Where the business is, optional"
    },
    "language": {
      "type": "string",
      "description": "Language for the captions, optional (default: the business's own)"
    },
    "what_to_promote": {
      "type": "string",
      "description": "Something to feature in one post, optional (e.g. weekend brunch)"
    }
  },
  "required": [
    "business_name"
  ],
  "additionalProperties": false
}

Use this when someone wants popular or trending songs to put on a Reel, TikTok or Story for a business in Malaysia, Singapore, Indonesia, Philippines, Thailand, United States, Canada, United Kingdom, Australia or the UAE, for example 'what songs are trending in Malaysia for Reels?'. Returns this week's songs charting on both Apple Music and Spotify in that country, with the trend (new, up, down) and whether a business account can use them. It is a music-chart signal, not a count of Reels or TikTok uses. Every song is marked business use 'unknown' with the platform's official rule: say so, and never tell a business a song is cleared. Not for picking royalty-free music or for countries outside the list.

{
  "type": "object",
  "properties": {
    "country": {
      "type": "string",
      "description": "Country name or 2-letter code, e.g. Malaysia or MY"
    },
    "platform": {
      "type": "string",
      "enum": [
        "instagram",
        "tiktok",
        "any"
      ],
      "description": "Which app the post is for (changes the business-account rule shown). Default any."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 20,
      "description": "How many songs (default 10)"
    }
  },
  "required": [
    "country"
  ],
  "additionalProperties": false
}

Use this when someone planning posts, promotions or opening hours needs the public holidays, state holidays or big shopping/observance days for Malaysia, Singapore, Indonesia, Philippines, Thailand, United States, Canada, United Kingdom, Australia or the UAE, for example 'when is Hari Raya this year' or 'holidays in Malaysia next month'. Returns dates verified against the official government list and a second independent calendar, which regions/states each one applies to, and lunar holidays that are expected but not yet confirmed (clearly marked). Do not use it for other countries, for school terms, or to invent dates it doesn't return.

{
  "type": "object",
  "properties": {
    "country": {
      "type": "string",
      "description": "Country name or 2-letter code, e.g. Malaysia or MY"
    },
    "from": {
      "type": "string",
      "description": "Start date YYYY-MM-DD, optional (default today)"
    },
    "to": {
      "type": "string",
      "description": "End date YYYY-MM-DD, optional (default a year from the start)"
    }
  },
  "required": [
    "country"
  ],
  "additionalProperties": false
}

Use this when someone asks when to post on Instagram, Facebook or TikTok in Kuala Lumpur, Penang, Johor Bahru, Singapore, Jakarta, Manila, Bangkok, New York, Los Angeles, Toronto, Vancouver, London, Sydney, Melbourne or Dubai (or one of those countries). Returns windows in that city's local time where two large 2026 studies (Sprout Social and Buffer) agree, shows where they disagree instead of picking one, and adds what we measured ourselves (restaurants and cafes in the Suara Restaurant Index, and Suara clients when there are enough posts). Do not use it for other cities, for a specific account's own best time, or to promise results.

{
  "type": "object",
  "properties": {
    "city": {
      "type": "string",
      "description": "City or country, e.g. Kuala Lumpur, KL, Toronto or Malaysia"
    },
    "platform": {
      "type": "string",
      "description": "instagram, facebook or tiktok; optional (all three when left out)"
    },
    "category": {
      "type": "string",
      "description": "Kind of business, e.g. cafe or salon; optional"
    }
  },
  "required": [
    "city"
  ],
  "additionalProperties": false
}

Use this when the signed-in owner asks what Suara knows about their business or how their posts will sound. Returns their brand as Suara has it locked: name, voice, audience, colours, what they sell, and the notes they've given ("less pink", "never say cheap"). Read only. Changes nothing.

{
  "type": "object",
  "properties": {},
  "required": [],
  "additionalProperties": false
}

Use this when the signed-in owner wants to see this week's posts, what's coming up, or what a post looks like. Returns each post's caption, hashtags, day and status (being made, ready to review, waiting for approval, scheduled, posted), shown in the Suara viewer with every slide. Give postId to see one post. Read only. Nothing is posted.

{
  "type": "object",
  "properties": {
    "postId": {
      "type": "string",
      "description": "Only this post (with every carousel slide)"
    },
    "images": {
      "type": "boolean",
      "description": "Also attach the pictures to the answer (default false: the Suara viewer shows them)"
    }
  },
  "required": [],
  "additionalProperties": false
}

Use this when the signed-in owner has a request, idea or feedback for the Suara team who make their posts: what to post about, a promotion or event coming up, a change to a post (say which postId), a new look, more or fewer posts. Write the request clearly and completely in the owner's words. It sends a message to the team (nothing is posted or changed right away); the team replies later, so check with get_suara_replies.

{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "description": "What the owner wants, in full",
      "minLength": 3,
      "maxLength": 3000
    },
    "postId": {
      "type": "string",
      "description": "The post it's about, if any"
    }
  },
  "required": [
    "message"
  ],
  "additionalProperties": false
}

Use this when the signed-in owner asks if there's news from the Suara team, or after send_to_suara. Returns the team's replies and updates from the last few days (7 by default, up to 30): answers to their requests, posts ready to review, what was posted. Read only.

{
  "type": "object",
  "properties": {
    "days": {
      "type": "number",
      "description": "How many days back (default 7, max 30)"
    }
  },
  "required": [],
  "additionalProperties": false
}

Use this only when the signed-in owner has clearly said to approve or post one specific post, after they've seen it. It schedules that post to be published on the owner's connected social accounts on its day (or right away if they say now). Publishing can't be undone from here. One post per call; it fails if the post isn't finished or no account is connected.

{
  "type": "object",
  "properties": {
    "postId": {
      "type": "string",
      "description": "The post to approve"
    },
    "when": {
      "type": "string",
      "enum": [
        "its_day",
        "now"
      ],
      "description": "its_day (default): its planned day at their usual time. now: right away."
    }
  },
  "required": [
    "postId"
  ],
  "additionalProperties": false
}

Use this when the signed-in owner wants to connect their Instagram, Facebook Page or TikTok so approved posts can be published. Returns a secure link (valid for an hour) to the platform's own login page; Suara never sees their password. Instagram must be a Business or Creator account. Nothing is posted by connecting.

{
  "type": "object",
  "properties": {
    "platform": {
      "type": "string",
      "enum": [
        "instagram",
        "facebook",
        "tiktok"
      ]
    }
  },
  "required": [
    "platform"
  ],
  "additionalProperties": false
}

Use this when the signed-in owner asks which social accounts Suara can post to. Returns each connected platform and its username. Read only.

{
  "type": "object",
  "properties": {},
  "required": [],
  "additionalProperties": false
}

Use this when the signed-in owner asks what to post, when to post, or how their Instagram is doing. Returns what's working on their own public Instagram: when they post, which posts do better, recurring themes. Read only.

{
  "type": "object",
  "properties": {},
  "required": [],
  "additionalProperties": false
}