SambungAPI
Plain-language answers to the words SambungAPI uses. Nothing here assumes you have read anything else.
A key belongs to the project, not to one connected account. One key reaches every account in its project, which is why a key for staging can never touch production.
Read these in order. A project lives inside an organization, and the last two both live inside a project. The picture above is the same four words drawn out.
An organization is your company's own space in SambungAPI. Everyone you invite joins it, every project you make belongs to it, and the bill is addressed to it.
Two organizations are sealed off from each other. Nothing you create is visible to another company, and nothing another company creates is visible to you.
Most businesses need exactly one. You would make a second only if you ran two businesses that should never share anything.
A project is one app inside your organization, or one copy of an app. A common setup is two projects: one called production that serves real customers, and one called staging where you try things out.
Each project keeps its own connected accounts, its own keys, and its own logs. That separation is the point: a test that goes wrong in staging cannot touch a customer in production, because the two never share a key or an account.
A connected account is one person's permission for your app to act in one outside service, stored inside one project.
Every connected account is filed under a user id, and your code sends that same id as user_id when it runs a tool. There are two ways to make one, and they file it under different ids.
From your application: a user of your app clicks Connect Gmail, and Google asks them to approve it. Your code created that connect link with the id you gave that application user, so SambungAPI files the approval under it. From then on your code says 'send this mail as user 8142' and SambungAPI knows which approval to use.
From the console: when you connect a tool in the console, SambungAPI files the connected account under your own principal id, which starts with p_, and deletes it when you leave the organization or delete your account. Each project connects its own. A caller can share one account in a project by connecting it with the user id org: followed by your organization id; the Connected accounts page lists such an account as project-wide. The Connected accounts page shows the user_id of every row, with a Copy button.
You never handle the password, and you never store the token. If the user withdraws the permission later, the connected account stops working and nothing else does.
An API key is a long secret string your code sends with every call, so SambungAPI knows which project the call belongs to.
There are two kinds and the console names them apart. A project key belongs to one project and runs tool work. A Warta key belongs to your organization and drives WhatsApp sending. Neither one can sign a person in.
SambungAPI shows a key once, when you create it, and keeps only a fingerprint afterwards. That is deliberate: if nobody can read a key back out of the console, a stolen console session cannot hand your keys to anybody. It also means a key you lose is replaced, never recovered.
Make one key per place that calls you, so that revoking a leaked one takes down that one caller and leaves the rest running.
These are the six that most often stop a first read. Each one also appears as a hint beside its first use elsewhere in the console.
A principal is one actor SambungAPI can put a name to. You are a principal when you sign in. So is a script that runs at 3am with a key of its own and no person watching.
Everything is filed under the principal that did it: which role you hold, which keys are yours, and every line in the audit trail. That is what lets the question 'who did this' always have an answer.
You and a colleague are two principals even when you work in the same company, which is why one of you can be removed without disturbing the other.
A namespace names the service that vouched for a sign-in. It is the front half of a full identifier: the namespace, a colon, and then the id that service gave the person.
It exists because ids are only unique inside the place that issued them. Two sign-in services can both hand out the id 1042 to two unrelated people, so SambungAPI keeps the service's name beside the id and never lets the two collide.
Today every person signs in through Google's Firebase, with a Google account or with an email address and a password, so every person has the same namespace. A program that runs on its own can have a different one. You see it only where the console prints an identifier in full.
WABA is short for WhatsApp Business Account. Meta creates it for your business and it holds two things you will use constantly: the business phone numbers your customers message, and the templates, which are the wordings Meta has approved you to send first.
A bakery with one number for orders and another for deliveries keeps both inside a single WABA.
You connect a WABA to SambungAPI once. After that, SambungAPI can send and receive on every number inside it, and you manage the numbers and the templates from the SambungAPI console instead of from Meta's pages.
A toolkit is one outside service together with everything SambungAPI knows how to do in it. Gmail is a toolkit. So are Google Drive, Notion, and Google Calendar.
Open the Gmail toolkit and you find its actions: send an email, fetch the ones that match a search, download an attachment. Your code calls an action by name, and SambungAPI does the talking to Google.
Connecting is done per toolkit, once per user. After a user has approved Gmail, every Gmail action works for that user without asking again.
The control plane is the setting-up side of SambungAPI. It is the SambungAPI console, and the API that the console calls.
Inviting a teammate, creating a project, making a key, changing who is allowed to do what, and reading the audit trail are all control plane work. It is the part a person uses, occasionally, on purpose.
Your own customers never touch it. It is yours.
The data plane is the working side of SambungAPI. Once setting up is finished, this is the API your own code calls, thousands of times a day if your app is busy.
Send this WhatsApp message. Create that calendar event. Read those unread mails. Each call runs against an account one of your users already approved.
It takes a different key from the one that signs you into the console, and that separation is on purpose: a key that leaks out of your server can do the work your app does, and it cannot invite a person, change a role, or read your bill.
Each one also appears as a hint beside its first use on the WhatsApp pages of the console.
One person your business talks to, such as a customer or a colleague. It appears on its own at the first message between you.
A word your team puts on a person, such as VIP or wholesale, to find or choose them later. Only your organization sees it.
A message wording Meta approves in advance. Only an approved one can start a conversation, or reach someone who last wrote more than 24 hours ago.
A one-time marketing message to people you choose, such as news of a weekend sale. On WhatsApp it must use an approved marketing template.
A message to one person or group, sent when something happens in your business, such as an order shipping. Your own software starts it.
SambungAPI's hand-off of one event, such as a message someone sent you, to a web address your developer set up. It does not show whether your own messages arrived.
A web address that your organization registers under a name, so that SambungAPI passes events to your own software, such as a message someone sent you. A person adds one in the console, or a developer adds one with the API.
The code SambungAPI gives each event it passes on, starting with evt_. Search for it to see whether that one hand-off worked.
Connecting through a Meta window: you sign in with Facebook and choose the WhatsApp Business Account and the number to connect. You never copy a token.
Meta's name for keeping your number in the WhatsApp Business app while SambungAPI also uses it. Meta copies the app's messages and its address book to SambungAPI.
Connecting through your own Meta app: you give SambungAPI an access token from that app, and SambungAPI holds it safely to send for you.
The number Meta gives your WhatsApp Business Account, in digits only, such as 104839201847362. Copy it from WhatsApp Manager.
A secret you create in Meta Business settings for a system user: an account for software, not a person. Connecting through your own Meta app needs one.
The secret of your own Meta app, under App settings, Basic, in Meta for Developers. SambungAPI uses it to check that messages come from Meta.
SambungAPI safely holding the token that lets it send and receive for your WhatsApp Business Account. When Meta rejects that token, sending stops until it is repaired.
Meta's service for sending and receiving business messages on WhatsApp. SambungAPI works through it, so each number must be registered for it before sending.
Meta's name for the way Meta tells SambungAPI about new messages and status changes as they happen. Nothing arrives until it is verified.
The secret your software uses to send WhatsApp messages through SambungAPI. It can be limited to one phone number and is shown only once.
