Send a notification (email, SMS, etc.) to one user. Requires a notification `type` which categorizes this messages for future reporting, and channel-specific payloads such as `email` or `sms`. Recipient is specified with the `to` parameter. Returns a `trackingId` for error or delivery lookup through our Logs.
// Request body only
await pingram.send({
// See Request Body Properties table below for all available fields
// Example structure (adjust based on your needs):
// fieldName: 'value'
});
Parameters
Name
Type
Description
senderPostBody
SenderPostBody
See Request Body Properties below
Request Body Properties
Name
Type
Description
type
string
ID of the notification type (e.g. “welcome_email”). Creates a new notification if it does not exist.
to
object
Recipient user. Provide id, email, or number to identify the user.
to.id
string
Unique user identifier. Required.
to.email
string
User’s email address for email notifications.
to.number
string
User’s phone number for SMS/call notifications.
to.pushTokens
object[]
Mobile push tokens (FCM, APN) for push notifications.
to.pushTokens[].type
“FCM” | “APN”
(required)
to.pushTokens[].token
string
(required)
to.pushTokens[].device
object
(required)
to.pushTokens[].device.app_id
string
to.pushTokens[].device.ad_id
string
to.pushTokens[].device.device_id
string
(required)
to.pushTokens[].device.platform
string
to.pushTokens[].device.manufacturer
string
to.pushTokens[].device.model
string
to.pushTokens[].environment
string
used by APN to differentiate between sandbox and production builds (sandbox/undefined or production)
to.webPushTokens
object[]
Web push subscription config from the browser.
to.webPushTokens[].sub
object
(required) Configuration for a Push Subscription. This can be obtained on the frontend by calling serviceWorkerRegistration.pushManager.subscribe(). The expected format is the same output as JSON.stringify’ing a PushSubscription in the browser.
to.webPushTokens[].sub.endpoint
string
(required)
to.webPushTokens[].sub.keys
object
(required)
to.webPushTokens[].sub.keys.p256dh
string
(required)
to.webPushTokens[].sub.keys.auth
string
(required)
to.timezone
string
User’s timezone (e.g. “America/New_York”) for scheduling.
to.slackChannel
string
The destination channel of slack notifications sent to this user. Can be either of the following: - Channel name, e.g. “test” - Channel name with # prefix, e.g. “#test” - Channel ID, e.g. “C1234567890” - User ID for DM, e.g. “U1234567890” - Username with @ prefix, e.g. “@test”
to.slackToken
object
to.slackToken.access_token
string
to.slackToken.app_id
string
to.slackToken.authed_user
object
to.slackToken.authed_user.access_token
string
to.slackToken.authed_user.expires_in
number
to.slackToken.authed_user.id
string
to.slackToken.authed_user.refresh_token
string
to.slackToken.authed_user.scope
string
to.slackToken.authed_user.token_type
string
to.slackToken.bot_user_id
string
to.slackToken.enterprise
object
to.slackToken.enterprise.id
string
to.slackToken.enterprise.name
string
to.slackToken.error
string
to.slackToken.expires_in
number
to.slackToken.incoming_webhook
object
to.slackToken.incoming_webhook.channel
string
to.slackToken.incoming_webhook.channel_id
string
to.slackToken.incoming_webhook.configuration_url
string
to.slackToken.incoming_webhook.url
string
to.slackToken.is_enterprise_install
boolean
to.slackToken.needed
string
to.slackToken.ok
boolean
(required)
to.slackToken.provided
string
to.slackToken.refresh_token
string
to.slackToken.scope
string
to.slackToken.team
object
to.slackToken.team.id
string
to.slackToken.team.name
string
to.slackToken.token_type
string
to.slackToken.warning
string
to.slackToken.response_metadata
object
to.slackToken.response_metadata.warnings
string[]
to.slackToken.response_metadata.next_cursor
string
to.slackToken.response_metadata.scopes
string[]
to.slackToken.response_metadata.acceptedScopes
string[]
to.slackToken.response_metadata.retryAfter
number
to.slackToken.response_metadata.messages
string[]
to.lastSeenTime
string
Last activity timestamp. Updated automatically. Read-only.
to.updatedAt
string
Last update timestamp. Read-only.
to.createdAt
string
Creation timestamp. Read-only.
to.emailSuppressionStatus
object
Bounce or complaint status if email was suppressed. Read-only.
(required) Account whose saved payment method is copied onto the new account. The caller must be an owner of this account.
memberEmails
string[]
Emails to add or invite to the new account. Existing members of any account the caller belongs to are added directly; everyone else is invited.
listAccounts()
List accounts the authenticated user can access
// No parameters
await pingram.accounts.listAccounts();
Parameters
This endpoint does not need any parameter.
Addresses
createAddress()
Create a new email inbox. Omit `domain` for a built-in `@mail.pingram.io` address; set `domain` and `displayName` for a custom address on a verified domain.
// Request body only
await pingram.addresses.createAddress({
// See Request Body Properties table below for all available fields
// Example structure (adjust based on your needs):
// fieldName: 'value'
});
Parameters
Name
Type
Description
createAddressRequest
CreateAddressRequest
See Request Body Properties below
Request Body Properties
Name
Type
Description
prefix
string
(required)
domain
string
displayName
string
deleteAddress()
Delete a custom inbound address. Builtin addresses cannot be deleted.
Start removing all email suppressions of the given reason (`retryable` or `bounces`) for users in the environment. Returns immediately after the job is queued — suppressions are not yet cleared when this response is received. Large removals are processed in the background in batches.
Send an email. Requires `type`, `to`, `subject`, and `html`. Optional: `fromAddress`, `fromName`, `schedule`, attachments. The fromAddress must be a verified domain; otherwise our built-in address will be used which is fine for testing purposes.
// Request body only
await pingram.email.send({
// See Request Body Properties table below for all available fields
// Example structure (adjust based on your needs):
// fieldName: 'value'
});
Parameters
Name
Type
Description
sendEmailRequest
SendEmailRequest
See Request Body Properties below
Request Body Properties
Name
Type
Description
type
string
(required) The notification type to send.
to
string
(required) The email address of the recipient.
subject
string
(required) The subject of the email.
html
string
(required) The HTML body of the email.
fromName
string
The display name of the sender.
fromAddress
string
The email address of the sender.
previewText
string
The preview text of the email.
replyToAddresses
string[]
The reply-to addresses of the email.
ccAddresses
string[]
The CC addresses of the email.
bccAddresses
string[]
The BCC addresses of the email.
attachments
object[]
URL-based file attachments. Up to 20 MB per file.
attachments[].filename
string
(required)
attachments[].url
string
(required)
schedule
string
The ISO 8601 datetime to schedule the email.
Environments
listEnvironments()
Get all environments for the authenticated account
List active phone numbers registered for the account, including voice agent binding state.
// No parameters
await pingram.numbers.list();
Parameters
This endpoint does not need any parameter.
listReleased()
List released phone numbers. Released numbers may be purchased again with 2 weeks of being released. Released numbers may be removed from released list after 2 weeks.
// No parameters
await pingram.numbers.listReleased();
Parameters
This endpoint does not need any parameter.
orderNumber()
Purchase a phone number for the authenticated account, or reactivate a released number owned by the account (preserves original createdAt). Pass `phoneNumber` in E.164 format (e.g. +15551234567).
// Request body only
await pingram.numbers.orderNumber({
// See Request Body Properties table below for all available fields
// Example structure (adjust based on your needs):
// fieldName: 'value'
});
Parameters
Name
Type
Description
orderPhoneNumberRequest
OrderPhoneNumberRequest
See Request Body Properties below
Request Body Properties
Name
Type
Description
phoneNumber
string
(required) E.164 from search results
releaseNumber()
Release a phone number from the account. No refund for the current billing month.
(required) Legal entity type for a 10DLC brand. - PRIVATE_PROFIT: private for-profit (LLC, corp, etc.) - SOLE_PROPRIETOR: sole proprietorship - PUBLIC_PROFIT: publicly traded for-profit - NON_PROFIT: non-profit - GOVERNMENT: government
legalName
string
Official registered legal business name. For SOLE_PROPRIETOR, optional DBA or trade name (defaults to firstName and lastName).
displayName
string
(required) Public brand name shown to recipients and carriers. Use the name customers recognize (your DBA or trade name). For companies with no DBA, use the same value as legalName. For SOLE_PROPRIETOR, this is the brand you send as — not the individual’s legal name (set firstName and lastName for that). If the sole proprietor has no DBA, use first and last name.
firstName
string
Legal first name of the sole proprietor. Required when businessType is SOLE_PROPRIETOR.
lastName
string
Legal last name of the sole proprietor. Required when businessType is SOLE_PROPRIETOR.
taxId
string
For US companies (country US): 9-digit EIN (Employer Identification Number). For Canada (country CA): 9-digit BN (Business Number). For other countries: national business tax identifier. Required except when businessType is SOLE_PROPRIETOR.
website
string
(required) Public website for the brand. Include a scheme (https://) or a domain; https:// is prepended when omitted. Carriers expect a working site with privacy policy and terms.
country
string
(required) ISO 3166-1 alpha-2 country of incorporation (for example US or CA).
street
string
(required) Street address that matches official tax registration.
city
string
(required) City that matches official tax registration.
state
string
(required) State (US) or province (CA) that matches official tax registration.
postalCode
string
(required) ZIP code (US) or postal code (CA) that matches official tax registration.
complianceContactEmail
string
(required) Email for the 10DLC compliance contact. Used for carrier and registration follow-up.
complianceContactPhone
string
(required) Phone number for the 10DLC compliance contact. E.164 preferred; national numbers are normalized using country.
getUs10dlcBrand()
Get the 10DLC brand registration for the authenticated account. Returns null when no registration exists yet.
// No parameters
await pingram.registrations.getUs10dlcBrand();
Parameters
This endpoint does not need any parameter.
getUs10dlcCampaign()
Get the 10DLC campaign registration for the authenticated account. Returns null when no brand registration exists yet.
// No parameters
await pingram.registrations.getUs10dlcCampaign();
Parameters
This endpoint does not need any parameter.
updateUs10dlcBrand()
Update an existing 10DLC brand registration. Business fields are editable before carrier submission; workflow status is managed by Pingram.
// Request body only
await pingram.registrations.updateUs10dlcBrand({
// See Request Body Properties table below for all available fields
// Example structure (adjust based on your needs):
// fieldName: 'value'
});
Parameters
Name
Type
Description
tenDlcBrandUpdateRequest
TenDlcBrandUpdateRequest
See Request Body Properties below
Request Body Properties
Name
Type
Description
scenarioId
“own_brand” | “client_brand”
Who the 10DLC brand is registered for. - own_brand: personal or company project - client_brand: agency or contractor
Legal entity type for a 10DLC brand. - PRIVATE_PROFIT: private for-profit (LLC, corp, etc.) - SOLE_PROPRIETOR: sole proprietorship - PUBLIC_PROFIT: publicly traded for-profit - NON_PROFIT: non-profit - GOVERNMENT: government
legalName
string
Official registered legal business name. For SOLE_PROPRIETOR, optional DBA or trade name (defaults to firstName and lastName).
displayName
string
Public brand name shown to recipients and carriers. Use the name customers recognize (your DBA or trade name). For SOLE_PROPRIETOR, this is the brand you send as — not the individual’s legal name. Omit to keep the existing value. If you change legalName and omit displayName, displayName is reset to the new legalName.
firstName
string
Legal first name of the sole proprietor. Required when businessType is SOLE_PROPRIETOR.
lastName
string
Legal last name of the sole proprietor. Required when businessType is SOLE_PROPRIETOR.
taxId
string
For US companies (country US): 9-digit EIN (Employer Identification Number). For Canada (country CA): 9-digit BN (Business Number). For other countries: national business tax identifier. Required except when businessType is SOLE_PROPRIETOR.
website
string
Public website for the brand. Include a scheme (https://) or a domain; https:// is prepended when omitted. Carriers expect a working site with privacy policy and terms.
country
string
ISO 3166-1 alpha-2 country of incorporation (for example US or CA).
street
string
Street address that matches official tax registration.
city
string
City that matches official tax registration.
state
string
State (US) or province (CA) that matches official tax registration.
postalCode
string
ZIP code (US) or postal code (CA) that matches official tax registration.
complianceContactEmail
string
Email for the 10DLC compliance contact. Used for carrier and registration follow-up.
complianceContactPhone
string
Phone number for the 10DLC compliance contact. E.164 preferred; national numbers are normalized using country.
updateUs10dlcCampaign()
Update an existing 10DLC campaign registration. Campaign fields are editable before carrier submission; workflow status is managed by Pingram.
// See Request Body Properties table below for all available fields
// Example structure (adjust based on your needs):
// fieldName: 'value'
});
Parameters
Name
Type
Description
tenDlcCampaignUpdateRequest
TenDlcCampaignUpdateRequest
See Request Body Properties below
Request Body Properties
Name
Type
Description
campaignDescription
string
Summary of what this campaign sends and why, including audience and typical message content. Required before carrier submission.
campaignSample1
string
Example SMS that represents actual campaign traffic. Required before carrier submission. Should match the use case and typically identify the brand and include STOP/HELP language.
campaignSample2
string
Second example SMS. Required before carrier submission. Required for MARKETING and MIXED use cases.
campaignSample3
string
Optional third example SMS.
campaignSample4
string
Optional fourth example SMS.
campaignMessageFlow
string
How recipients opt in (for example website form, checkout, or keyword). Describe the call-to-action and where consent is collected. Required before carrier submission.
campaignOptinKeywords
string
Extra opt-in keywords as a comma-separated list. START is always included.
campaignOptinMessage
string
Auto-reply sent when a recipient opts in. Required before carrier submission. Should confirm the subscription, mention message frequency, and include STOP and HELP instructions.
campaignOptoutKeywords
string
Extra opt-out keywords as a comma-separated list. STOP is always included.
campaignOptoutMessage
string
Auto-reply sent when a recipient opts out. Required before carrier submission. Should confirm they will receive no further messages.
campaignHelpKeywords
string
Extra help keywords as a comma-separated list. HELP is always included.
campaignHelpMessage
string
Auto-reply sent when a recipient texts a help keyword. Required before carrier submission. Should include a support contact (email and/or phone).
campaignEmbeddedLink
boolean
Whether campaign messages include URLs.
campaignEmbeddedLinkUrl
string
Sample URL that appears in messages. Provide when campaignEmbeddedLink is true.
campaignEmbeddedPhone
boolean
Whether campaign messages include phone numbers.
campaignAgeGated
boolean
Whether campaign content is age-restricted (18+).
campaignDirectLending
boolean
Whether the campaign relates to direct lending or loan products.
campaignPrivacyPolicyLink
string
Public URL of the privacy policy that covers this SMS program.
campaignTermsAndConditionsLink
string
Public URL of the terms and conditions that cover this SMS program.
campaignUsecase
string
10DLC campaign use case submitted to carriers. Required before carrier submission. One of 2FA, ACCOUNT_NOTIFICATION, CUSTOMER_CARE, DELIVERY_NOTIFICATION, FRAUD_ALERT, MARKETING, MIXED, POLLING_VOTING, PUBLIC_SERVICE_ANNOUNCEMENT, or SECURITY_ALERT. For MIXED, append comma-separated sub-use cases after MIXED (sub-use cases cannot include MIXED), for example MIXED,2FA,ACCOUNT_NOTIFICATION.
Sender
deleteSchedule()
Delete (unschedule) an already scheduled notification
Update the body or schedule of an already scheduled notification.
// Path parameter + request body
await pingram.sender.updateSchedule('', {
// See Request Body Properties table below for all available fields
// Example structure (adjust based on your needs):
// fieldName: 'value'
});
Parameters
Name
Type
Description
trackingId
string
The tracking ID of the scheduled notification
senderPostBody
SenderPostBody
See Request Body Properties below
Request Body Properties
Name
Type
Description
type
string
ID of the notification type (e.g. “welcome_email”). Creates a new notification if it does not exist.
to
object
Recipient user. Provide id, email, or number to identify the user.
to.id
string
Unique user identifier. Required.
to.email
string
User’s email address for email notifications.
to.number
string
User’s phone number for SMS/call notifications.
to.pushTokens
object[]
Mobile push tokens (FCM, APN) for push notifications.
to.pushTokens[].type
“FCM” | “APN”
(required)
to.pushTokens[].token
string
(required)
to.pushTokens[].device
object
(required)
to.pushTokens[].device.app_id
string
to.pushTokens[].device.ad_id
string
to.pushTokens[].device.device_id
string
(required)
to.pushTokens[].device.platform
string
to.pushTokens[].device.manufacturer
string
to.pushTokens[].device.model
string
to.pushTokens[].environment
string
used by APN to differentiate between sandbox and production builds (sandbox/undefined or production)
to.webPushTokens
object[]
Web push subscription config from the browser.
to.webPushTokens[].sub
object
(required) Configuration for a Push Subscription. This can be obtained on the frontend by calling serviceWorkerRegistration.pushManager.subscribe(). The expected format is the same output as JSON.stringify’ing a PushSubscription in the browser.
to.webPushTokens[].sub.endpoint
string
(required)
to.webPushTokens[].sub.keys
object
(required)
to.webPushTokens[].sub.keys.p256dh
string
(required)
to.webPushTokens[].sub.keys.auth
string
(required)
to.timezone
string
User’s timezone (e.g. “America/New_York”) for scheduling.
to.slackChannel
string
The destination channel of slack notifications sent to this user. Can be either of the following: - Channel name, e.g. “test” - Channel name with # prefix, e.g. “#test” - Channel ID, e.g. “C1234567890” - User ID for DM, e.g. “U1234567890” - Username with @ prefix, e.g. “@test”
to.slackToken
object
to.slackToken.access_token
string
to.slackToken.app_id
string
to.slackToken.authed_user
object
to.slackToken.authed_user.access_token
string
to.slackToken.authed_user.expires_in
number
to.slackToken.authed_user.id
string
to.slackToken.authed_user.refresh_token
string
to.slackToken.authed_user.scope
string
to.slackToken.authed_user.token_type
string
to.slackToken.bot_user_id
string
to.slackToken.enterprise
object
to.slackToken.enterprise.id
string
to.slackToken.enterprise.name
string
to.slackToken.error
string
to.slackToken.expires_in
number
to.slackToken.incoming_webhook
object
to.slackToken.incoming_webhook.channel
string
to.slackToken.incoming_webhook.channel_id
string
to.slackToken.incoming_webhook.configuration_url
string
to.slackToken.incoming_webhook.url
string
to.slackToken.is_enterprise_install
boolean
to.slackToken.needed
string
to.slackToken.ok
boolean
(required)
to.slackToken.provided
string
to.slackToken.refresh_token
string
to.slackToken.scope
string
to.slackToken.team
object
to.slackToken.team.id
string
to.slackToken.team.name
string
to.slackToken.token_type
string
to.slackToken.warning
string
to.slackToken.response_metadata
object
to.slackToken.response_metadata.warnings
string[]
to.slackToken.response_metadata.next_cursor
string
to.slackToken.response_metadata.scopes
string[]
to.slackToken.response_metadata.acceptedScopes
string[]
to.slackToken.response_metadata.retryAfter
number
to.slackToken.response_metadata.messages
string[]
to.lastSeenTime
string
Last activity timestamp. Updated automatically. Read-only.
to.updatedAt
string
Last update timestamp. Read-only.
to.createdAt
string
Creation timestamp. Read-only.
to.emailSuppressionStatus
object
Bounce or complaint status if email was suppressed. Read-only.
Slack message metadata with optional work object entities. Combines standard Slack message metadata fields with an array of entity objects.
slack.metadata.entities
object[]
An array of work object entities.
slack.metadata.entities[].entity_type
string
(required) Entity type (e.g., ‘slack#/entities/task’, ‘slack#/entities/file’).
slack.metadata.entities[].entity_payload
Record<string, any>
(required) Schema for the given entity type.
slack.metadata.entities[].external_ref
object
(required) Reference used to identify an entity within the developer’s system.
slack.metadata.entities[].external_ref.id
string
(required)
slack.metadata.entities[].external_ref.type
string
slack.metadata.entities[].url
string
(required) URL used to identify an entity within the developer’s system.
slack.metadata.entities[].app_unfurl_url
string
The exact URL posted in the source message. Required in metadata passed to chat.unfurl.
slack.metadata.event_type
string
A human readable alphanumeric string representing your application’s metadata event.
slack.metadata.event_payload
Record<string, any>
A free-form object containing whatever data your application wishes to attach to messages.
Sms
send()
Send an SMS or MMS directly without a template. Requires `type` and `to`. Pass `message` and/or `mediaUrls`. Optional: `from`, `schedule`.
// Request body only
await pingram.sms.send({
// See Request Body Properties table below for all available fields
// Example structure (adjust based on your needs):
// fieldName: 'value'
});
Parameters
Name
Type
Description
sendSmsRequest
SendSmsRequest
See Request Body Properties below
Request Body Properties
Name
Type
Description
type
string
(required) The notification type to send.
to
string
(required) The phone number of the recipient.
message
string
The message of the SMS or MMS notification. Optional when mediaUrls is provided.
mediaUrls
string[]
Public HTTPS URLs of media to attach (MMS).
schedule
string
The ISO 8601 datetime to schedule the SMS notification.
from
string
Override the sender phone number. Must be a dedicated number on your Pingram account.
Templates
createTemplate()
Create a new template for a notification
// Path parameter + request body
await pingram.templates.createTemplate('', {
// See Request Body Properties table below for all available fields
// Example structure (adjust based on your needs):
// fieldName: 'value'
});
Parameters
Name
Type
Description
notificationId
string
Notification ID
channel
string
Channel type
templatePostRequest
TemplatePostRequest
See Request Body Properties below
Request Body Properties
Name
Type
Description
templateId
string
(required) Unique ID for this template within the notification and channel. Required.
html
string
HTML body of the email.
previewText
string
Preview text (e.g. for inbox).
internal
string
Internal editor representation of the email content (e.g. Bee or Redactor JSON). Used for editing and component embedding; the actual email sent to recipients uses the html field.
subject
string
Email subject line.
senderName
string
Sender display name.
senderEmail
string
Sender email address.
title
string
Notification title (in-app).
redirectURL
string
URL to open when the user taps the notification.
imageURL
string
Image URL shown in the in-app notification.
instant
object
Copy for instant (real-time) delivery.
instant.title
string
instant.redirectURL
string
instant.imageURL
string
(required)
batch
object
Copy for batch delivery.
batch.title
string
(required)
batch.redirectURL
string
(required)
batch.imageURL
string
(required)
text
string
Message text (SMS or call).
message
string
Push notification body text. (title is shared with INAPP_WEB above.)
icon
string
Web push: icon URL. Slack: bot icon (emoji or URL).
url
string
Web push: URL to open when the notification is clicked.
// See Request Body Properties table below for all available fields
// Example structure (adjust based on your needs):
// fieldName: 'value'
});
Parameters
Name
Type
Description
notificationId
string
Notification ID
channel
string
Channel type
templateId
string
Template ID
templatePatchRequest
TemplatePatchRequest
See Request Body Properties below
Request Body Properties
Name
Type
Description
html
string
HTML body of the email.
previewText
string
Preview text (e.g. for inbox).
internal
string
Internal editor representation of the email content (e.g. Bee or Redactor JSON). Used for editing and component embedding; the actual email sent to recipients uses the html field.
subject
string
Email subject line.
senderName
string
Sender display name.
senderEmail
string
Sender email address.
title
string
Notification title (in-app).
redirectURL
string
URL to open when the user taps the notification.
imageURL
string
Image URL shown in the in-app notification.
instant
object
Copy for instant (real-time) delivery.
instant.title
string
instant.redirectURL
string
instant.imageURL
string
(required)
batch
object
Copy for batch delivery.
batch.title
string
(required)
batch.redirectURL
string
(required)
batch.imageURL
string
(required)
text
string
Message text (SMS or call).
message
string
Push notification body text. (title is shared with INAPP_WEB above.)
icon
string
Web push: icon URL. Slack: bot icon (emoji or URL).
url
string
Web push: URL to open when the notification is clicked.
blocks
Record<string, any>[]
Slack message blocks (optional).
username
string
Slack bot username.
Types
createNotificationType()
Create a new notification
// Request body only
await pingram.types.createNotificationType({
// See Request Body Properties table below for all available fields
// Example structure (adjust based on your needs):
Get account-level metadata including logo, VAPID key, and web push status
// No parameters
await pingram.user.getAccountMetadata();
Parameters
This endpoint does not need any parameter.
getInAppNotifications()
Get in-app notifications for a user
// No parameters
await pingram.user.getInAppNotifications();
Parameters
Name
Type
Description
before
string
Timestamp or ISO date to fetch notifications before
count
number
Number of notifications to return (default 10)
getInAppUnreadCount()
Get the count of unread in-app notifications for a user
// No parameters
await pingram.user.getInAppUnreadCount();
Parameters
This endpoint does not need any parameter.
getUser()
Get a user by ID. All users exist implicitly, returns basic user object if not found in DB.
// Path parameter only
await pingram.user.getUser('userId_example');
Parameters
Name
Type
Description
userId
string
User ID
identify()
Create or update a user with the given ID. Updates lastSeenTime automatically.
// Path parameter + request body
await pingram.user.identify('', {
// See Request Body Properties table below for all available fields
// Example structure (adjust based on your needs):
// fieldName: 'value'
});
Parameters
Name
Type
Description
userId
string
User ID
postUserRequest
PostUserRequest
See Request Body Properties below
Request Body Properties
Name
Type
Description
id
string
Unique user identifier. Required.
email
string
User’s email address for email notifications.
number
string
User’s phone number for SMS/call notifications.
pushTokens
object[]
Mobile push tokens (FCM, APN) for push notifications.
pushTokens[].type
“FCM” | “APN”
(required)
pushTokens[].token
string
(required)
pushTokens[].device
object
(required)
pushTokens[].device.app_id
string
pushTokens[].device.ad_id
string
pushTokens[].device.device_id
string
(required)
pushTokens[].device.platform
string
pushTokens[].device.manufacturer
string
pushTokens[].device.model
string
pushTokens[].environment
string
used by APN to differentiate between sandbox and production builds (sandbox/undefined or production)
webPushTokens
object[]
Web push subscription config from the browser.
webPushTokens[].sub
object
(required) Configuration for a Push Subscription. This can be obtained on the frontend by calling serviceWorkerRegistration.pushManager.subscribe(). The expected format is the same output as JSON.stringify’ing a PushSubscription in the browser.
webPushTokens[].sub.endpoint
string
(required)
webPushTokens[].sub.keys
object
(required)
webPushTokens[].sub.keys.p256dh
string
(required)
webPushTokens[].sub.keys.auth
string
(required)
timezone
string
User’s timezone (e.g. “America/New_York”) for scheduling.
slackChannel
string
The destination channel of slack notifications sent to this user. Can be either of the following: - Channel name, e.g. “test” - Channel name with # prefix, e.g. “#test” - Channel ID, e.g. “C1234567890” - User ID for DM, e.g. “U1234567890” - Username with @ prefix, e.g. “@test”
slackToken
object
slackToken.access_token
string
slackToken.app_id
string
slackToken.authed_user
object
slackToken.authed_user.access_token
string
slackToken.authed_user.expires_in
number
slackToken.authed_user.id
string
slackToken.authed_user.refresh_token
string
slackToken.authed_user.scope
string
slackToken.authed_user.token_type
string
slackToken.bot_user_id
string
slackToken.enterprise
object
slackToken.enterprise.id
string
slackToken.enterprise.name
string
slackToken.error
string
slackToken.expires_in
number
slackToken.incoming_webhook
object
slackToken.incoming_webhook.channel
string
slackToken.incoming_webhook.channel_id
string
slackToken.incoming_webhook.configuration_url
string
slackToken.incoming_webhook.url
string
slackToken.is_enterprise_install
boolean
slackToken.needed
string
slackToken.ok
boolean
(required)
slackToken.provided
string
slackToken.refresh_token
string
slackToken.scope
string
slackToken.team
object
slackToken.team.id
string
slackToken.team.name
string
slackToken.token_type
string
slackToken.warning
string
slackToken.response_metadata
object
slackToken.response_metadata.warnings
string[]
slackToken.response_metadata.next_cursor
string
slackToken.response_metadata.scopes
string[]
slackToken.response_metadata.acceptedScopes
string[]
slackToken.response_metadata.retryAfter
number
slackToken.response_metadata.messages
string[]
markInAppNotificationsAsSeen()
Mark in-app web notifications as seen/read for a user
// Request body only
await pingram.user.markInAppNotificationsAsSeen({
// See Request Body Properties table below for all available fields
// Example structure (adjust based on your needs):
// fieldName: 'value'
});
Parameters
Name
Type
Description
inAppNotificationUnreadClearRequest
InAppNotificationUnreadClearRequest
See Request Body Properties below
Request Body Properties
Name
Type
Description
notificationId
string
trackingId
string
updateInAppNotificationStatus()
Update in-app web notification status (opened, archived, clicked, etc.)