Connect a CRM

How to build VeloConnect messaging into a CRM such as Pipedrive or Bitrix24, or into your own back
office. The same pattern works for any system that keeps people and wants to message them.

What the person who connects enters

Ask for three things once, on your connector's settings page:

the e-mail of a VeloConnect account,

its password,

the company's API key (on the API page of the VeloConnect dashboard, shown as General Key).

Sign in with Sign in (for programs) to check them. Then keep them encrypted on your server.
Never send them to the browser and never write them to a log.

TIP

Use a VeloConnect account made for the integration, without two-step sign-in. An account with two-step sign-in
gets no token from the program sign-in.

Which credential for which job

Job	Calls	Signed with
Send a message from a contact card or an automation	Send SMS, Send a Viber campaign, Send a WhatsApp campaign	API key
Fill drop-down lists (sender names, templates)	List sender names, List Viber templates, List WhatsApp templates	API key
Show the balance	Check balance	API key
Sync contacts and run campaigns	Contacts (v2), Segments (v2), Campaigns (v2)	Login token
Show message history of a person	List a contact's messages	Login token

Most connectors only need the API key. Add the login token when you sync contacts or run campaigns.

Sending from a CRM record

Write the number in international format before you send: country code first, no 00, no spaces. CRMs
often hold local numbers; convert them with the record's country. See
Addresses and formats.

Put the CRM's own id in uid, for example deal-5512-msg-3. It comes back in the answer and in the
delivery report, so you can find the record again without keeping a lookup table.

Read status in the answer. S means accepted; write message_id on the CRM activity. F means refused;
show remarks to the user.

On HTTP 429 wait the seconds in Retry-After and send again. In an automation that sends to many records,
send them one after another over a few connections, not all at once. See Limits.

Showing the delivery result

Give callback_url in the send call, pointing at an address of your connector with a long random part.
When the report arrives, find the CRM record by uid and update the activity. Answer HTTP 200. The full
field list is in Delivery reports.

If your connector cannot receive calls, ask instead with List SMS records a minute or two
after sending.

The token is short-lived. Renew it with Refresh the login token before tokenLifeTime
ends; a refresh token works once, so store the new pair every time. If a refresh answers 401, sign in again
with the stored credentials. Do this in one place in your code and make sure two workers do not refresh at
the same moment, or one of them will hold a used refresh token.

Things that catch connector builders

Allowed IP addresses. If the company has set a list of allowed addresses for its key, calls from your
cloud are refused with 401 unless your addresses are on the list. Publish your connector's outgoing
addresses so customers can add them.

One key per company. If the company replaces its key, your connector gets 401 until the new key is
entered. Show a clear "reconnect" message for 401.

The key is a secret. Anyone who has it can send messages at the company's cost. Keep it server-side only.

Connect a CRM

What the person who connects enters#

Which credential for which job#

Sending from a CRM record#

Showing the delivery result#

Keeping the login token alive#

Things that catch connector builders#

What the person who connects enters

Which credential for which job

Sending from a CRM record

Showing the delivery result

Keeping the login token alive

Things that catch connector builders