Business Messenger Contacts API
1. Overview
The Business Messenger (BM) API is a standard REST HTTP API with JSON payload. It can be used to programmatically manage BM contact data. BM API authorization is implemented as the industry-standard OAuth2 protocol.
The API base URL is:
https://api{separator}{platform_domain}/news/v1
Note: Replace {platform_domain} with your platform domain. {separator} can be either . or -, depending on your platform configuration.
2. Getting credentials
In order to be able to use the API, you need to provide a name for your custom app, IP address from which you will be authorizing the app and the BM account name whose contacts data your app will be managing. It is expected that your app will be a server-side implementation and as such will use the OAuth2 client credentials grant type.
In return, the support team will create an API account for your app and you will be given: client_id and client_secret credentials.
3. Authorization
In order to be able to call any API endpoint, you need to obtain a valid access token. Each access token has an expiration time so you need to obtain a new one if the existing one is expired. Here's a cURL example of how an access token can be obtained (please replace CLIENT_ID and CLIENT_SECRET with the ones you were given in the previous step):
curl https://accounts{separator}{platform_domain}/oauth2/access-token -d 'grant_type=client_credentials&client_id=CLIENT_ID&client_secret=CLIENT_SECRET'
If the parameters are valid, and the call is made from the authorized IP address, the server will respond with JSON containing the access token:
{"access_token":"ACCESS_TOKEN","token_type":"Bearer","expires_in":604800}
4. Call API endpoints
Having a valid access token you are ready to access API endpoints of your choice. Here's a sample cURL call that adds a new contact in your BM account.
Note: A domain is presented with placeholders as https://api{separator}{platform_domain}, where {separator} can be a dot (.) or a hyphen (-). Please, replace it with your actual platform domain name.
curl -X POST --header "Content-Type: application/json" --header "Accept: application/json" --header "Authorization: Bearer ACCESS_TOKEN" -d "{
\"list_uuid\": \"LIST_UUID\",
\"first_name\": \"John\",
\"last_name\": \"Smith\",
\"mobile\": \"+12025550100\",
\"email\": \"john@example.com\",
\"address\": \"St One\",
\"zip\": \"9000\",
\"city\": \"NY\",
\"country\": \"US\"
\"opt_status\": \"in\"
}" "https://api{separator}{platform_domain}/news/v1/services/SERVICE_UUID/cds/contacts"
Note that in order to have a contact opted in for SMS campaigns, you need to explicitly set field opt_status to in value, or PATCH this contact with this opt_status later.
or search for a contact(s) having mobile number: +41764986185 :
curl --header "Accept: application/json" --header "Authorization: Bearer ACCESS_TOKEN" "https://api{separator}{platform_domain}/news/v1/services/SERVICE_UUID/cds/contacts?mobile=%2B41764986185"
In many cases adding contacts one by one would be an overkill. imports endpoint is there to provide batch import:
curl -X POST "https://api{separator}{platform_domain}/news/v1/services/SERVICE_UUID/cds/imports?list_uuid=LIST_UUID&resolve_duplicate=update&identifier=mobile" \
-H "accept: application/json" \
-H "Content-Type: application/json" \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-d @- << EOF
[
{"mobile":"+41765554366","first_name":"John","last_name":"Smith"},
{"mobile":"+41765554783","first_name":"Mike","last_name":"Collins"},
{"mobile":"+41775559513","first_name":"George","last_name":"Davis"}
]
EOF
identifier=mobile defines that existing and new contacts will be identified and mapped by mobile field.
resolve_duplicate=update if duplicates are found, existing records will be updated with the new data.