API keys, a JSON API and webhooks
Connect your own systems to SmartMy Marketing. API keys let them add contacts with consent and start journeys. Webhooks tell them at once when a contact is added, a cart is paid or someone opts out.
PLANSFrom Growth
The problem it solves
- Leads from your own app or booking site are exported and imported by hand every week.
- Your CRM never hears that a customer opted out on WhatsApp.
- Developers ask for a way to start a journey from your system, and there is none.
- Shared passwords are used for integrations, and nobody knows which tool did what.
How it works
- An administrator opens Marketing > Configuration > Integrations > New API Key. Name it and choose Acts As, the user whose rights the key has.
- Press Make the Key and copy it at once: it is not shown again, only its start is kept.
- Your system calls https://<your address>/ht/mkt/api/v1/ with the key in Authorization: Bearer, or X-Api-Key.
- For webhooks, open Integrations > Webhooks > New, choose When, and give Call This Address. A signing secret is made for you.
- Each record of that kind is sent once, right after it is first saved, made or changed, as JSON with X-SmartMy-Event and X-SmartMy-Signature headers.
- The Calls tab shows each call: Waiting, Delivered or Failed. Failed calls are tried again every 15 minutes, up to 5 attempts.
Everything it does
The API
- GET ping: checks the key, gives the Entity and the user
- POST contacts: adds or finds a contact by email, else phone. Fields: name, email, phone, company, city, tags, lead_list, columns (name: value). Also consent (channel: proof) for email, WhatsApp or SMS
- GET journeys: the running journeys and sequences
- POST journeys/<id>/enrol: puts a contact (contact_id or email) into a running journey
- JSON in and out; errors come back with a message and status 400 or 401
API keys
- One key per tool, in one Entity
- Acts As: calls do only what that user may do
- Key Starts With and Last Used on each key; only a hash of the key is stored
- Revoke: calls with the key stop at once
Webhook events
- A Contact Is Added; A Form Is Sent; A Lead Comes From an Ad; A Customer Writes (Any Channel)
- A Chat Cart Is Paid; An Order Is Credited to Marketing; Someone Opts Out
- Someone Finishes a Journey; An Online Store Order Comes In
- An event whose feature you do not have is refused ("This event needs a feature that is not installed")
Webhook calls
- Body: event, model, id, Entity, time and the record's main fields
- X-SmartMy-Signature: the hex HMAC-SHA256 of the body with the signing secret
- Each record is sent once per webhook
- A webhook sends only its Entity's records; contacts only those its Entity may reach
- Call This Address must be a public internet address; one inside your network or on the server is refused. Redirects are not followed
- Calls tab: when, record, the answer code, attempts, error and status
Who uses it
Marketing AdministratorMakes and revokes keys, sets up webhooks and reads their calls.
Your developerCalls the API and checks the signature of each webhook.
Where you use it
- Web: Marketing > Configuration > Integrations > API Keys, New API Key and Webhooks
- Your systems: https://<your address>/ht/mkt/api/v1/
- Not built: ready-made apps on automation platforms; use their webhook and HTTP steps with this API
What you control
Settings
- Per key: name, Acts As, Entity
- Per webhook: When, Call This Address, Signing Secret (made for you), active
Questions
Can our booking site add leads with WhatsApp consent?
Yes. Send consent with the channel and the proof, such as the wording of your form. It is recorded on the contact as an opt-in through the API.What if our server is down when a webhook fires?
The call is marked Failed and tried again every 15 minutes, up to 5 attempts in all. Each call is listed on the webhook's Calls tab.How do we know a webhook really came from SmartMy?
Each call carries X-SmartMy-Signature, the HMAC-SHA256 of the body with your signing secret. Compute it and compare.Can a key do everything?
A key does only what its Acts As user may do, in its Entity. Pick a user with just the rights the integration needs.Is there documentation?
The calls and fields are listed in the SmartMy Marketing manual. A separate developer site is not built.Related features
AI AND SELLINGRevenue by sourceEvery confirmed order, online store order and paid chat cart is credited to the customer's last marketing touch. You see which broadcast, sequence, lead ad or chat brought money, not only clicks.CAMPAIGNSJourneys: triggers, waits, If / Else, tags, tasks and goalsAutomate what happens after someone enters. Wait, send an email or WhatsApp message, and branch on a reply or a tag. Tag people, give someone a task, and end at your goal.AUDIENCEConsent per contact, channel and Entity, with STOP and STARTEvery opt-in and every withdrawal is kept per person, channel and Entity, with where it came from and its proof. STOP in a chat or an unsubscribe click is recorded by itself, and WhatsApp marketing goes only to people who said yes.AUDIENCEForms with their own page or an embed scriptBuild a sign-up or enquiry form in Marketing, share its own page or paste one script line into any website. Each entry becomes a contact with its consent and proof, joins your list and journey, and gives someone a follow-up task.AUDIENCELeads from Facebook, Instagram and Google lead adsLeads from your Facebook and Instagram lead forms, and from Google Ads lead forms by webhook, arrive as contacts with every answer. Each form sends its leads to a list, tags, a journey and a person who calls them.AI AND SELLINGShopify, WooCommerce and Magento storesConnect your Shopify, WooCommerce or Magento store. Its products become products to sell in chat. Its customers and orders come in, so journeys can thank, follow up and win back each buyer.
See your inbox and campaigns on it.
Tell us which channels your customers use, how leads reach you and how many people answer them. We will connect a channel with you and run your first journey.