Guides

Sync Messages from Podium Conversations

Suggest Edits

Podium allows you to send and receive messages through Facebook Messenger, Google Business Messaging, text messaging, email, and Instagram all while centralizing these conversations into your Podium Inbox.

Message webhook APIs let you subscribe and keep track of every message both sent and received.

1575

📘

Working with webhook events

Podium messages are currently available via webhook events. To configure and subscribe to these events, read the Webhook guide first.

At a glance

Invoices let a business request and receive payments via Podium. Payment readers are the physical terminal that allows the business to collect payments for card-present transactions.

Podium's Message Webhook API allows you to receive the following events:

  • Messages Sent. Outbound messages sent by the business (Podium location) to the end consumer.
  • Messages Received. Inbound messages sent from the end consumer.
  • Messages Failed. Outbound messages that attempted to send but were not delivered.

What you'll need

  • A Webhook URL endpoint
  • Client ID and Secret for OAuth access token
  • Test account for sending and receiving messages

Receive message events

To begin receiving message events, you will need to reach out to Podium to configure your webhook URL. You will also need to have a user provide access to that location's message data via the OAuth grant flow (make sure to include the correct scope).

Once your webhook has been configured and a user has authorized your application to receive Message events, you will begin receiving data for every message sent and received.

Key attributes provided in the event include the following:

  • Contact. Contact information will include the contact name and Podium's unique identifier associated with the contact.
  • Conversation Channel. The channel is the method and messaging platform used to send the message. Examples of channels include SMS (phone), email, Facebook Messenger, Google, Apple Business Chat, etc. The channel identifier is the value needed to deliver the message (phone is the phone number, email is the email address).
  • Conversation Assignment. Conversations can either remain unassigned or be tied to a user who often is responsible for messaging the contact. User assignments will include a Podium user UID that can be referenced with the Users API.
  • Location. Both location and organization UIDs are provided with each message. These unique identifiers are the Podium account associated with the message and can be found via the Podium Locations API.
  • Sender. Sender information with either include a UID for a user or the contact (customer) information depending on the message type (message sent or message received).
1052

Conversation and message atributes

Message sent event

🚧

Deprecations

The contact and sender object fields have been deprecated, they are currently only available in webhooks and will be completely removed at some point in the future.

{
    "data": {
        "body": "Thanks for your payment, John. View your receipt from ABC Clinic for $550.00: http://pay.podium.co/a2Ajsdfe",
        "contact": {
            "externalIdentifier": null,
            "name": "Ana",
            "uid": "c1ee21d0-9ebd-4eac-8d6a-c25b30ae3775"
        },
        "conversation": {
            "assignedUser": {
                "name": null,
                "uid": null
            },
            "channel": {
                "identifier": "+13236167777",
                "type": "phone"
            },
            "startedAt": "2021-06-25T20:26:37.507100Z",
            "uid": "58f2022d-3c42-4d05-9a0b-4bbfb9c68236"
        },
        "createdAt": "2021-06-29T21:36:52.684589Z",
        "failureReason": null,
        "location": {
            "organizationUid": "4915e432-f1df-5b17-a03c-efb54bee1e1e",
            "uid": "4e43239b-4e86-5a5a-a76a-de655a8484ea"
        },
        "sender": {
            "uid": null
        },
        "uid": null
    },
    "metadata": {
        "eventType": "message.sent",
        "version": "2021.04.01"
    }
}

require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://api.podium.com/v4/invoices")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["podium-version"] = '2021.4.1'
request["Content-Type"] = 'application/json'
request.body = "{\"locationUid\":\"9483748s-3a1c-5537-a31b-442ca560593d\",\"customerName\":\"John Smith\",\"channelIdentifier\":\"[email protected]\",\"lineItems\":[{\"Amount\":\"10000\",\"Description\":\"Chair\"}],\"readerUid\":\"46525as-3a1c-5537-a31b-442ca560593d\",\"invoiceNumber\":\"IN-3240ASD\"}"

response = http.request(request)
puts response.read_body

const options = {
  method: 'POST',
  headers: {'podium-version': '2021.4.1', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    locationUid: '9483748s-3a1c-5537-a31b-442ca560593d',
    customerName: 'John Smith',
    channelIdentifier: '[email protected]',
    lineItems: [{Amount: '10000', Description: 'Chair'}],
    readerUid: '46525as-3a1c-5537-a31b-442ca560593d',
    invoiceNumber: 'IN-3240ASD'
  })
};

fetch('https://api.podium.com/v4/invoices', options)
  .then(response => console.log(response))
  .catch(err => console.error(err));

import requests

url = "https://api.podium.com/v4/invoices"

payload = {
    "locationUid": "9483748s-3a1c-5537-a31b-442ca560593d",
    "customerName": "John Smith",
    "channelIdentifier": "[email protected]",
    "lineItems": [
        {
            "Amount": "10000",
            "Description": "Chair"
        }
    ],
    "readerUid": "46525as-3a1c-5537-a31b-442ca560593d",
    "invoiceNumber": "IN-3240ASD"
}
headers = {
    "podium-version": "2021.4.1",
    "Content-Type": "application/json"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)

Occasionally, you may receive a message failed event. For example, if the outbound message was sent to a landline instead of a phone that can receive SMS text messages.

See the below example of a webhook event for a message that failed to send:

{
	"data": {
		"body": "Hello",
		"contact": {
			"externalIdentifier": null,
			"name": "Brandon Tyson",
			"uid": "8f1c7fca-8d87-4f82-a0a2-18907ebbedfe"
		},
		"conversation": {
			"assignedUser": {
				"name": null,
				"uid": null
			},
			"channel": {
				"identifier": "+18014890896",
				"type": "phone"
			},
			"startedAt": "2021-07-01T08:17:27.824975Z",
			"uid": "7206d08f-7e5d-4928-b2e5-5b80d1af834r"
		},
		"createdAt": "2021-07-01T08:17:27.895070Z",
		"failureReason": "landline",
		"location": {
			"organizationUid": "4915e1a7-f1df-5b17-a03c-efb54betee1e",
			"uid": "4e87d39b-4e86-5a5a-a76a-de655a8484ea"
		},
		"sender": {
			"uid": "71f99893-068a-5a3e-9c19-ef37d4d69278"
		},
		"uid": "b5de248b-3583-4b65-8ab9-042391b06857"
	},
	"metadata": {
		"eventType": "message.failed",
		"eventUid": "6f4b7811-a4d9-4074-a420-9775a2d33231",
		"version": "2021.04.01"
	}
}

Congratulations!

Congratulations, you now know how to receive events via Podium's webhook API for all messages being sent and received by a business.

Updated about 3 years ago

What’s Next