Llamadas

Llama desde tus números (Marsial llama a la persona y la conecta con tu teléfono, una dirección SIP o un agente de voz con IA), lee el historial con grabaciones y transcripciones y calcula lo que cuesta una llamada.

Historial de llamadas de un número

GET/v1/phone-numbers/{id}/calls

Entrantes y salientes, de la más reciente a la más antigua.

Parámetros

• idstringobligatorio
• cursorstring
• directionstring

  Valores: inbound · outbound

• limitinteger

  máx. 100

Respuesta 200

data

• itemsobject[]obligatorio
  items

  • idstringobligatorio

    call_…

  • numberIdstringobligatorio
  • channelstringobligatorio

    pstn (teléfono).

  • directionstringobligatorio

    Valores: inbound · outbound

  • fromstringobligatorio
  • tostringobligatorio
  • statusstringobligatorio

    dialing, ringing, answered, ended, failed, no_answer…

  • endReasonstring
  • durationSecondsnumber
  • recordingbooleanobligatorio
  • transcriptSnippetstring
  • transcriptobject[]

    Solo en GET /calls/{id}.

    transcript

    • textstringobligatorio
    • atstring
  • costnumber

    Euros.

  • startedAtstring
  • endedAtstring
• nextCursorstring | nullobligatorio

  Envíalo como cursor para la página siguiente; null en la última.

curl

curl "https://api.marsial.dev/v1/phone-numbers/num_…/calls" \
  -H "Authorization: Bearer $MARSIAL_API_KEY"

Node

const res = await fetch('https://api.marsial.dev/v1/phone-numbers/num_…/calls', {
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
  },
});
const { data } = await res.json();

Python

import os, requests

res = requests.get(
    "https://api.marsial.dev/v1/phone-numbers/num_…/calls",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
)
data = res.json()["data"]

Llamar a alguien

POST/v1/calls

Marsial llama a to desde tu número y, cuando contesta, le conecta con forwardTo (tu teléfono, una dirección SIP o un agente de voz) o con el destino de entrada del número.

Cuerpo

• numberIdstringobligatorio

  El número que llama (num_…).

• tostringobligatorio

  A quién llamar.

• forwardTostring

  Con quién conectarle cuando conteste; si no, el destino de entrada del número.

  máx. 500

• greetingstring

  Se le dice al contestar, antes de conectar.

  máx. 500

• recordboolean
• transcribeboolean
• idempotencyKeystring

  máx. 100

Respuesta 201

data

• idstringobligatorio

  call_…

• numberIdstringobligatorio
• channelstringobligatorio

  pstn (teléfono).

• directionstringobligatorio

  Valores: inbound · outbound

• fromstringobligatorio
• tostringobligatorio
• statusstringobligatorio

  dialing, ringing, answered, ended, failed, no_answer…

• endReasonstring
• durationSecondsnumber
• recordingbooleanobligatorio
• transcriptSnippetstring
• transcriptobject[]

  Solo en GET /calls/{id}.

  transcript

  • textstringobligatorio
  • atstring
• costnumber

  Euros.

• startedAtstring
• endedAtstring

curl

curl -X POST "https://api.marsial.dev/v1/calls" \
  -H "Authorization: Bearer $MARSIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "numberId": "num_…",
    "to": "+447700900123",
    "forwardTo": "tel:+447700900456"
  }'

Node

const res = await fetch('https://api.marsial.dev/v1/calls', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "numberId": "num_…",
    "to": "+447700900123",
    "forwardTo": "tel:+447700900456"
  }),
});
const { data } = await res.json();

Python

import os, requests

res = requests.post(
    "https://api.marsial.dev/v1/calls",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
    json={
        "numberId": "num_…",
        "to": "+447700900123",
        "forwardTo": "tel:+447700900456"
    },
)
data = res.json()["data"]

Lo que costaría una llamada

GET/v1/calls/estimate

Parámetros

• tostringobligatorio
• minutesinteger

  Por defecto: 5máx. 600

• numberIdstring

  El número que llamaría: la respuesta dice además si puede llegar a to.

Respuesta 200

data

• destinationCountrystring
• minutesintegerobligatorio

  máx. 9.007.199.254.740.991

• perMinutenumberobligatorio

  Euros por minuto.

• totalnumberobligatorio

  Euros por los minutos pedidos.

• reachableboolean

  Con numberId: false cuando ese número solo llama dentro de su país.

• notestring

curl

curl "https://api.marsial.dev/v1/calls/estimate?to=%2B447700900123&minutes=5" \
  -H "Authorization: Bearer $MARSIAL_API_KEY"

Node

const res = await fetch('https://api.marsial.dev/v1/calls/estimate?to=%2B447700900123&minutes=5', {
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
  },
});
const { data } = await res.json();

Python

import os, requests

res = requests.get(
    "https://api.marsial.dev/v1/calls/estimate?to=%2B447700900123&minutes=5",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
)
data = res.json()["data"]

Ver una llamada

GET/v1/calls/{id}

Con su transcripción si la transcripción estaba activada.

Parámetros

• idstringobligatorio

Respuesta 200

data

• idstringobligatorio

  call_…

• numberIdstringobligatorio
• channelstringobligatorio

  pstn (teléfono).

• directionstringobligatorio

  Valores: inbound · outbound

• fromstringobligatorio
• tostringobligatorio
• statusstringobligatorio

  dialing, ringing, answered, ended, failed, no_answer…

• endReasonstring
• durationSecondsnumber
• recordingbooleanobligatorio
• transcriptSnippetstring
• transcriptobject[]

  Solo en GET /calls/{id}.

  transcript

  • textstringobligatorio
  • atstring
• costnumber

  Euros.

• startedAtstring
• endedAtstring

curl

curl "https://api.marsial.dev/v1/calls/call_…" \
  -H "Authorization: Bearer $MARSIAL_API_KEY"

Node

const res = await fetch('https://api.marsial.dev/v1/calls/call_…', {
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
  },
});
const { data } = await res.json();

Python

import os, requests

res = requests.get(
    "https://api.marsial.dev/v1/calls/call_…",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
)
data = res.json()["data"]

Grabación de una llamada

GET/v1/calls/{id}/recording

Un enlace al MP3 que funciona 15 minutos. Solo llamadas grabadas (por ajuste o por llamada).

Parámetros

• idstringobligatorio

Respuesta 200

data

• urlstringobligatorio

  Funciona 15 minutos.

curl

curl "https://api.marsial.dev/v1/calls/call_…/recording" \
  -H "Authorization: Bearer $MARSIAL_API_KEY"

Node

const res = await fetch('https://api.marsial.dev/v1/calls/call_…/recording', {
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
  },
});
const { data } = await res.json();

Python

import os, requests

res = requests.get(
    "https://api.marsial.dev/v1/calls/call_…/recording",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
)
data = res.json()["data"]

Colgar

POST/v1/calls/{id}/end

Parámetros

• idstringobligatorio

Respuesta 204

Sin contenido

curl

curl -X POST "https://api.marsial.dev/v1/calls/call_…/end" \
  -H "Authorization: Bearer $MARSIAL_API_KEY"

Node

const res = await fetch('https://api.marsial.dev/v1/calls/call_…/end', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
  },
});
const { data } = await res.json();

Python

import os, requests

res = requests.post(
    "https://api.marsial.dev/v1/calls/call_…/end",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
)
data = res.json()["data"]

Transferir una llamada en curso

POST/v1/calls/{id}/transfer

A otro teléfono (+E164) o a una dirección SIP; la llamada sale de tu control.

Parámetros

• idstringobligatorio

Cuerpo

• tostringobligatorio

Respuesta 204

Sin contenido

curl

curl -X POST "https://api.marsial.dev/v1/calls/call_…/transfer" \
  -H "Authorization: Bearer $MARSIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+447700900789"
  }'

Node

const res = await fetch('https://api.marsial.dev/v1/calls/call_…/transfer', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "to": "+447700900789"
  }),
});
const { data } = await res.json();

Python

import os, requests

res = requests.post(
    "https://api.marsial.dev/v1/calls/call_…/transfer",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
    json={
        "to": "+447700900789"
    },
)
data = res.json()["data"]