JavaScript

import Surge from '@surgeapi/node';

const client = new Surge({
  apiKey: 'My API Key',
});

const message = await client.messages.create('acct_01j9a43avnfqzbjfch6pygv1td', {
  conversation: { contact: { phone_number: '+18015551234' } },
});

console.log(message.id);

{
  "attachments": [
    {
      "id": "att_01j9e0m1m6fc38gsv2vkfqgzz2",
      "type": "image",
      "url": "https://api.surge.app/attachments/att_01jbwyqj7rejzat7pq03r7fgmf"
    }
  ],
  "body": "Thought you could leave without saying goodbye?",
  "conversation": {
    "contact": {
      "first_name": "Dominic",
      "id": "ctc_01j9dy8mdzfn3r0e8x1tbdrdrf",
      "last_name": "Toretto",
      "phone_number": "+18015551234"
    },
    "id": "cnv_01j9e0dgmdfkj86c877ws0znae",
    "phone_number": {
      "id": "pn_01jsjwe4d9fx3tpymgtg958d9w",
      "number": "+18015552345",
      "type": "local"
    }
  },
  "id": "msg_01j9e0m1m6fc38gsv2vkfqgzz2"
}

Messages

Create message

Creates and enqueues a new message to be sent.

Messages are always sent asynchronously. When you hit this endpoint, the message will be created within Surge’s system and enqueued for sending, and then the id for the new message will be returned. When the message is actually sent, a message.sent webhook event will be triggered and sent to any webhook endpoints that you have subscribed to this event type. Then a message.delivered webhook event will be triggered when the carrier sends us a delivery receipt.

By default all messages will be sent immediately. If you would like to schedule sending for some time up to 60 days in the future, you can do that by providing a value for the send_at field. This should be formatted as an ISO8601 datetime like 2028-10-14T18:06:00Z.

You must include either a body or attachments field (or both) in the request body. The body field should contain the text of the message you want to send, and the attachments field should be an array of objects with a url field pointing to the file you want to attach. Surge will download these files and send them as attachments in the message.

You can provide either a conversation object or a to field to specify the intended recipient of the message, but an error will be returned if both fields are provided. Similarly the from field cannot be used together with the conversation field, and conversation.phone_number should be specified instead.

POST

accounts

{account_id}

messages

JavaScript

import Surge from '@surgeapi/node';

const client = new Surge({
  apiKey: 'My API Key',
});

const message = await client.messages.create('acct_01j9a43avnfqzbjfch6pygv1td', {
  conversation: { contact: { phone_number: '+18015551234' } },
});

console.log(message.id);

{
  "attachments": [
    {
      "id": "att_01j9e0m1m6fc38gsv2vkfqgzz2",
      "type": "image",
      "url": "https://api.surge.app/attachments/att_01jbwyqj7rejzat7pq03r7fgmf"
    }
  ],
  "body": "Thought you could leave without saying goodbye?",
  "conversation": {
    "contact": {
      "first_name": "Dominic",
      "id": "ctc_01j9dy8mdzfn3r0e8x1tbdrdrf",
      "last_name": "Toretto",
      "phone_number": "+18015551234"
    },
    "id": "cnv_01j9e0dgmdfkj86c877ws0znae",
    "phone_number": {
      "id": "pn_01jsjwe4d9fx3tpymgtg958d9w",
      "number": "+18015552345",
      "type": "local"
    }
  },
  "id": "msg_01j9e0m1m6fc38gsv2vkfqgzz2"
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

account_id

string

required

The account from which the message should be sent.

Example:

"acct_01j9a43avnfqzbjfch6pygv1td"

Body

application/json

Payload for creating a message. Either an attachment or the body must be given. You can specify the recipient either using the 'conversation' parameter or the 'to'/'from' parameters, but not both. Create a message while including parameters for the conversation in which the message should be sent.

conversation

object

required

Params for selecting or creating a new conversation. Either the id or the Contact must be given.

Show child attributes

Example:

{
  "contact": {
    "first_name": "Dominic",
    "last_name": "Toretto",
    "phone_number": "+18015551234"
  },
  "phone_number": "+18015556789"
}

attachments

AttachmentParams · object[]

Show child attributes

body

string

The message body.

send_at

string<date-time>

An optional datetime for scheduling message up to a couple of months in the future.

Response

Created message

A Message is a communication sent to a Contact.

attachments

Attachment · object[]

Show child attributes

body

string

The message body.

conversation

object

A conversation with a Contact

Show child attributes

Example:

{
  "contact": {
    "first_name": "Dominic",
    "id": "ctc_01j9dy8mdzfn3r0e8x1tbdrdrf",
    "last_name": "Toretto",
    "phone_number": "+18015551234"
  },
  "id": "cnv_01j9e0dgmdfkj86c877ws0znae",
  "phone_number": {
    "id": "pn_01jsjwe4d9fx3tpymgtg958d9w",
    "number": "+18015552345",
    "type": "local"
  }
}

string

Unique identifier for the object.

Update contact Purchase phone number

API Reference

Webhooks

Create message

Authorizations

Path Parameters

Body

Response