API access

Your code can talk to Banga in four ways. Each has its own credentials, and only the first three are meant for apps.

Which API to use

API	What it is for	Credentials	Read more
Webhooks	The platform calls your server when a member runs a command, submits a form, taps a card button or pays.	Signed requests you verify with your app's secret	Webhooks
`/bot-api/v1`	Post cards into rooms your app was added to.	Room bot token, `bbt_...`	Room bots
`/app-api/v1`	Look up payments, refund them and pay members out.	Payments key, `bpk_...`	Payments
`/api`	The REST API the Banga apps themselves use.	A signed-in member's access token	API reference

Tokens and keys are shown once in the developer console; only a hash of each is stored. Keep them on your server, never in a web page or a mobile app.

The REST API reference

The API reference documents every /api endpoint with its parameters, request and response bodies and error answers. The same description is available as an OpenAPI document at /v3/api-docs/api-traffic.

Every call needs Authorization: Bearer <access token>. Access tokens are short-lived and are issued only by the apps' sign-in: a phone number, an SMS code and a registered device.
There are no API keys for /api. Never ask members for their tokens; an app gets what it needs from the platform, with the member's consent, as described under What an app can know.
/api is not versioned and changes together with the apps. Build integrations on webhooks, /bot-api/v1 and /app-api/v1, which are versioned.

An example call

curl "https://dev.banga.chat/bot-api/v1/rooms/ROOM_ID/cards" \
  -X POST \
  -H "Authorization: Bearer bbt_..." \
  -H "Content-Type: application/json" \
  -d '{ "blocks": [ { "type": "title", "text": "Hello from my app" } ] }'

Answers and errors for each API are listed on its own page and under Limits and errors.