WhatsApp

Explore 4 actions and their permissionsExact inputs, sign-in scopes, access limits and approval rules.

With WhatsApp connected, a hire can send your customers approved message templates (a payment reminder, say), reply to them freely while a conversation is open, see which templates it may use, and read what customers wrote. When a customer writes, the hire can be woken to answer.

It uses Meta's official WhatsApp Business Platform (the Cloud API), with your own business number. Messages go out from that number, in your business's name.

How WhatsApp's rules workCopy Anchor Link

• Templates are messages you write in advance and Meta approves. They're the only way to start a conversation, or to write to someone who hasn't written to you in the last 24 hours. Reminders should be utility templates; anything with an offer or discount counts as marketing.
• The 24-hour window: when a customer writes to you, you can reply with any message for 24 hours. Each new message from them starts the 24 hours again. After that, only templates.

Hires follow both rules. If a hire tries to write freely outside the window, it's told to use a template instead.

1. Set up WhatsApp with MetaCopy Anchor Link

You need a Meta Business account with the WhatsApp Business Platform set up and a phone number added. Then, in Meta:

1. A token: open System users in your Meta Business settings (the form in Roster links there too), add a system user, give it full control of your app and WhatsApp account, and click Generate token. Choose the permissions business_management, whatsapp_business_management and whatsapp_business_messaging, and no expiry if you're offered the choice. Copy the token.
2. The IDs: in your app's dashboard, open WhatsApp → API Setup and copy the Phone number ID and the WhatsApp Business Account ID.
3. The app secret: in your app's dashboard, open App settings → Basic and copy the App secret.
4. Templates: in WhatsApp Manager → Message templates, create the templates hires will use and wait for them to be approved.

To message more than a few customers a day, Meta asks you to verify your business. It also limits new numbers to 250 customers a day at first, and raises the limit as you send.

2. Connect it in RosterCopy Anchor Link

1. Open Integrations → Tools → Add a tool, search for WhatsApp and choose it.
2. Fill in:
   • Access token: the system user's token.
   • Phone number ID and WhatsApp Business Account ID.
   • Business name: your business's name, like Bayt Studio.
   • App secret: from your app's settings.
   • Webhook verify token: make up a long random text, and keep it for the next step.
3. Click Connect. Roster checks the token on your phone number, and the connection shows Connected as the number's verified business name. If Meta refuses the token (wrong, or expired), Roster says so and saves nothing.

3. Let customers' messages reach RosterCopy Anchor Link

After connecting, the connection shows the address WhatsApp should send messages to, with a Copy address button.

1. In your app's dashboard, open WhatsApp → Configuration → Webhook and click Edit.
2. Callback URL: paste the address. Verify token: the same text you put in Roster.
3. Click Verify and save, then subscribe to the messages field.

From then on, customers' messages arrive in Roster. Roster checks every message really comes from WhatsApp, using the app secret, and ignores anything else.

4. Give hires accessCopy Anchor Link

On the hire's Tools tab, click Give access on WhatsApp:

• Read only: it can see the templates and read conversations, and nothing else.
• Read and write: it can also send templates and messages.
• Who it may message: full numbers like +971501234567, or country codes like +971. Leave it empty to let it message anyone.
• Templates: the template names it may send. Leave it empty for every approved template.

First messages to new numbersCopy Anchor Link

A template to a number nobody here has been in touch with (no message either way) waits for a person's approval: the hire asks in the thread with the number, the template and its values, and when the approver says yes, Roster sends exactly that. After that, messages to them don't ask. To change this for a hire, use When it asks first on its Tools tab.

Saying it's an AI assistantCopy Anchor Link

A hire never pretends to be a person, and always says it's AI when asked. If you also want it to say so up front, turn on Say it's an AI assistant in first messages to outsiders under Settings → Workspace (more). Then:

• the first message a hire writes to someone starts with "This is the AI assistant for" and your business name;
• templates can't be changed when they're sent, so the first template to someone has to say it itself. Make one that does, like Hello {{1}}, this is the AI assistant for Bayt Studio…. A hire won't send another template as a first message.

Using AI to message your own customers is allowed by Meta. Its rules also ask that customers can reach a person: hires offer to bring in someone from your team when asked.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {}
}

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "to": {
      "type": "string",
      "minLength": 5,
      "description": "the customer's number with country code, like +971501234567"
    },
    "template": {
      "type": "string",
      "minLength": 1,
      "description": "the template's name, from list_templates"
    },
    "language": {
      "description": "e.g. en_US or ar; needed only when the template has several",
      "type": "string",
      "minLength": 2
    },
    "values": {
      "default": [],
      "description": "the body's values: a list for {{1}}, {{2}}…, or an object for named ones",
      "anyOf": [
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {
            "type": "string"
          }
        }
      ]
    }
  },
  "required": [
    "to",
    "template"
  ]
}

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "to": {
      "type": "string",
      "minLength": 5,
      "description": "the customer's number with country code, like +971501234567"
    },
    "text": {
      "type": "string",
      "minLength": 1,
      "maxLength": 4096
    }
  },
  "required": [
    "to",
    "text"
  ]
}

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "number": {
      "description": "the customer's number; leave out for the latest conversations",
      "type": "string",
      "minLength": 5
    },
    "limit": {
      "default": 30,
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  }
}