Sample Code

Below is a reference implementation written in Python, which illustrates the following functions of the Webhook API:

• Connection / Authentication
• Member Invite / Onboarding
• Add Member to Subcommunity
• Upsert Custom Member Data
• Send Direct Message to Member

import os
from requests_oauthlib import OAuth2Session

# Required Special Strings for OAuth 2 activation
oauth_client_id = ":uuid" # OAuth client ID
oauth_client_secret = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" # Provided separately for each client
oauth_token_uri = "https://api.community.com/oauth/v1/token"
oauth_authorization_url = 'https://oauth-login.community.com'
oauth_redirect_uri = "TBD" # Default, can be updated on request

base_url = "https://api.community.com"

# Create an OAuth2Session to orchestrate the authentication process
oauth_client = OAuth2Session(oauth_client_id, redirect_uri=oauth_redirect_uri, scope=[])
print("OAuth 2 session created", oauth_client)

# Initial request to being OAuth process
authorization_url, state = oauth_client.authorization_url(oauth_authorization_url)
print("Please complete the process by visiting this URL: ", authorization_url)

# Obtained from the browser's URL bar after successful authentication
# will look like https://oauth-login.community.com/TBD?code=secret_code_string
authorization_response = input('Please paste the full callback URL from your browser URL bar: ')
print("You entered: ", authorization_response)

# Performs code exchange for JWT token, which can be used to make requests
# You can use the oauth helper methods (see below), or you can include an { Authorization: Bearer <JWT> } header.
token = oauth_client.fetch_token(oauth_token_uri, include_client_id=oauth_client_id, client_secret=oauth_client_secret, authorization_response=authorization_response)
client_id = token["community_client_id"] # the Client ID of the Community account you authenticated
auth_token = token["access_token"] # The 60 min JWT
refresh_token = token["refresh_token"] # The OAuth refresh token

# Refresh setup
oauth_client.auto_refresh_url = f'https://api.community.com/oauth/v1/clients/{token["community_client_id"]}/refresh'
oauth_client.auto_refresh_kwargs = {
    "client_id": oauth_client_id,
    "client_secret": oauth_client_secret,
}

print(f"Authorization Successful! \nCommunity Client ID: {client_id}\nJWT: {auth_token}\nRefresh Token: {refresh_token}")

# At this point, you are authenticated - below inputs are helpful for testing individual onboarding actions
member_phone = input("Please enter your 10/11 digit phone number to onboard yourself to this client: ")
member_first_name = input("Please enter your first name: ")
member_last_name = input("Please enter your last name: ")
member_zip_code = input("Please enter your zip code: ")

# Member object to be sent as JSON to /subscription_create endpoint
member_object = {
    "phone_number": member_phone,
    "given_name": member_first_name,
    "surname": member_last_name,
    "postal_code": member_zip_code,
    "city": "Nashville",
    "date_of_birth": "1989-09-23",
    "gender": "male", # one of male, female, non-binary, no-answer
    "state_or_province": "Tennessee",
    "state_or_province_abbreviation": "TN",
    "geolocation": {
        "latitude": 36.122360650730045,
        "longitude": -86.77781258055839
    }
}

# Perform the onboarding request
# oauth.post is a helper method that uses the previously defined OAuth2Session
result = oauth_client.post(f"{base_url}/webhooks/v1/community/{client_id}/subscription_create", json=member_object)
print("Result of onboarding command", result)

# Add Member to a community list
add_member_to_community_object = {
    "tag": "Snooze Community", # string name of community
    "phone_number": member_phone,
    "operation": "add" # one of add, remove
}

# Perform request to add / remove Member from community list
add_result = oauth_client.post(f"{base_url}/webhooks/v1/community/{client_id}/subscription_tag_modify", json=add_member_to_community_object)
print("Result of modify community command", add_result)

# Send Member a direct message
send_direct_message_object = {
    "phone_number": member_phone,
    "text": f"You are the coolest! Thanks for signing up, {member_first_name}!"
}

# Perform request to send 1:1 DM to Member
dm_result = oauth_client.post(f"{base_url}/webhooks/v1/community/{client_id}/message_send", json=send_direct_message_object)
print("Result of DM command", dm_result)

# Update CMD for Member
cmd_object = {
    "phone_number": member_phone,
    "custom_fields": {
        "shirt_size": "large",
        "order_count": 100,
        "total_spend": 999.99,
        "rewards_member": "true",
        "first_purchase_date": "1970-01-01T00:00:00Z"
    }
}

cmd_result = oauth_client.post(f"{base_url}/webhooks/v1/community/{client_id}/subscription_field_value_modify", json=cmd_object)
print("Result of CMD set", cmd_result.json)

# That's it!
print("All done! Thanks for using Community.")