/v1/start_conversation

Time	Status	User Agent
Retrieving recent requests…

This endpoint starts a new conversation by sending a message through the same phone number and email address that you have configured in Apptoto. It can be used by 3rd party systems or internal systems to send one-time messages to clients. Messages sent through this API will count against your credit limit.

(This endpoint was previously named /v1/send_message. That path continues to work as an alias, but new integrations should use /v1/start_conversation.)

ACCESS:

Using a template (template_id): available to any account, as long as the template has no pending content approval. If the template is awaiting content approval, the request is rejected until the template is approved.
Sending free-form content (message / subject): requires the Send Message API permission to be enabled on your account. Please request it by contacting Apptoto Support.

If you are looking to sending automatic messages before or after actual "appointments", then please consider using Apptoto's Auto Messages. Apptoto Auto Messages know how to handle appointments moving, rescheduling, confirmation, etc. You will avoid building a lot of infrastructure by using them for those use cases. If you're unsure what tool to use, please contact [email protected].

The request body should look like the following:

{
  to: "+16505551212",
  type: "sms",
  message: "Hi there!"
}

In that case, Apptoto will send the message to the specific phone number provided.

You could instead send a message to an Event or a specific Participant on an event by using the event_id or participant_id field. When doing that, you can use dynamic fields. E.g.

{
  participant_id: "123456",
  type: "sms",
  message: "Hi there {{ name }}!  You're upcoming appointment is at {{ event.start_time | date_and_time_phrase }}."
}

To send an approved template instead of free-form content, provide a template_id and omit message/subject:

{
  participant_id: "123456",
  type: "sms",
  template_id: "default_appointment_reminder_sms"
}

Parameter Definitions:

Field	Type	Description
type	String	Should be "sms", "call", or "email".
to	String (Required unless event_id or participant_id is provided)	Should be the phone number or email address to send the message to.
event_id	Integer (Required unless to or participant_id is provided)	The id of an Apptoto Event that should receive the message. Each participant in the event will receive a copy of the message individually.
participant_id	Integer (Required)	The id of a specific Apptoto Participant that should receive the message.
message	String (Required unless template_id is specified)	The message to be sent.
subject	String	The subject of the email to be sent.
template_id	String	The id of an Apptoto template to send. This can be a built-in template name (e.g. "default_appointment_reminder_sms") or the numeric id of one of your own templates, which can be found on the Messaging > Templates page in the Apptoto portal. See /v1/conversation_templates for the list of templates you can use. When a template is used, the message and subject fields are ignored (the content comes from the template), and the template must not have a pending content approval.

Example Result:

{ 
  success: true
}

OAuth scope

Calls authenticated with an OAuth 2.0 bearer token must include the messaging:send scope. A token without it receives a 403 insufficient_scope response. HTTP Basic auth is not scope-gated.