Skip to main content
Custom apps let you give an integration access to selected WhatsApp Business phone numbers and YCloud APIs. Each app has its own API key, API permissions, and webhook configuration. Use a custom app when you want to limit an integration to the assets and capabilities it needs.

​
Before you begin

Make sure that:
  • Your account uses a paid YCloud plan. Custom apps are not available on the Free plan.
  • Your role can access Developers > Custom apps in the YCloud dashboard.
  • The WhatsApp Business phone numbers that the app needs are already available in your YCloud account.
  • You know which API permissions the integration needs.
  • You have a publicly reachable HTTPS endpoint if the app needs webhook events.
Keep the app API key and webhook signing secret in a secret manager. Never expose them in client-side code, logs, screenshots, or source control.

​
Create an app

  1. Sign in to the YCloud dashboard.
  2. Go to Developers > Custom apps.
  3. Click Create app.
Custom apps page in the YCloud dashboard with the Create app button.
  1. Enter an App name. The name can contain up to 64 characters.
  2. Optional: Enter a Description of up to 512 characters so your team knows what the app is used for.
  3. Click Create.
Create app dialog with App name and Description fields.

Enter an app name and, optionally, a description before selecting Create.

YCloud assigns the app a read-only app ID. A new app is disabled until you explicitly enable it. Configure its assets, API access, and webhook events before enabling it.

​
Assign WhatsApp phone numbers

Assign only the phone numbers that the integration needs to access.
  1. Open the app and select Assets.
  2. Click Add phone numbers.
Assets section of a custom app with the Add phone numbers button.
  1. Find a number by its Business Manager name, WABA ID, WABA name, or phone number.
  2. Select one or more WhatsApp Business phone numbers.
  3. Click Confirm.
The selection window also shows each number’s binding status and quality rating when that information is available.
Add phone numbers dialog showing available WhatsApp Business phone numbers, binding status, and quality rating.
The selected numbers now appear in the app’s asset list.

​
Configure the API key and permissions

YCloud displays the app’s API key in API key & permissions. Custom app keys start with yc_ak_. Use the copy action to store the key securely, then add only the permissions the integration requires.
API key and permissions section for a custom app.
  1. Select API key & permissions.
  2. Under API permissions, click Add permissions.
  3. Filter by category or search by permission name or scope.
  4. Select each required permission. For example, contact permissions are separated into read, create or update, and delete scopes.
  5. Click Confirm.
Edit permissions dialog showing contact permission scopes.
Send the generated key in the X-API-Key header, and use it only from trusted server-side code. YCloud checks that the app is active and that the request matches one of its selected API permissions. When an API operates on a WhatsApp asset, YCloud also checks that the app can access the relevant phone number or WABA. Not every YCloud API is available to custom apps. An API that does not appear in the permission selector is denied for a custom app key. Custom app keys also cannot be combined with the X-Managed-Account-ID header. See Authentication for the request header and credential-handling guidance.
The API key section includes an action to generate a replacement key. Depending on the option you choose during regeneration, the previous key is revoked immediately or remains available for a one-hour transition period. Update every service that uses the key before the transition period ends.

​
Configure webhooks

Configure a dedicated destination for the events that this app needs. App webhooks are separate from webhook endpoints configured under Developers > Webhooks.
  1. Select Webhook.
  2. Enter your public HTTPS endpoint in Endpoint URL and save it.
  3. Store the generated Signing secret securely.
  4. Under Added events, click Add events.
Webhook section with Endpoint URL, Signing secret, and Added events settings.
  1. Filter by category or search by event name or event type.
  2. Select the events that your endpoint must receive.
  3. If an event offers data-scope options, choose the scope that matches your integration.
  4. Click Confirm.
Add webhook events dialog showing available contact events.
YCloud delivers only selected events to an active app endpoint. WhatsApp events are filtered against the app’s assigned phone numbers or their parent WABAs. Event-specific data-scope settings can further limit delivery to data attributed to the app. Contact and unsubscribe events are tenant-level because they are not associated with a WhatsApp asset. Your endpoint should validate the YCloud signature before processing a request and return a successful 2xx response promptly. See Configure webhooks for signature validation, delivery handling, and security guidance. See Webhook event payloads for event schemas.

​
Enable and verify the app

Before using the app in production:
  1. Confirm that the app contains the expected WhatsApp Business phone numbers.
  2. Review every API permission and remove access the integration does not need.
  3. Return to Developers > Custom apps and enable the app from its actions menu.
Custom apps list with the Enable action for an inactive app.
  1. Confirm that the app status is Active.
  2. Send a test request with the app API key from a secure server-side environment.
  3. Trigger a selected event and confirm that your endpoint validates and processes it.
Only active apps can authenticate API requests or receive webhook events. You can find an existing app by its name or app ID. Open Edit to review or update its configuration.